Skip to content

HTTP Client

David Ciulla edited this page Nov 7, 2026 · 1 revision

HTTP Client

Laravex includes a lightweight outbound HTTP client in Laravex.Http.Client. It wraps OTP's built-in :httpc module and exposes a fluent, Laravel-style API for making HTTP requests, including full support for faking and asserting in tests.


Making Requests

Simple One-Liners

alias Laravex.Http.Client

# GET
response = Client.get("https://api.example.com/users")

# POST with a body
response = Client.post("https://api.example.com/users", %{name: "Alice", email: "alice@example.com"})

# PUT, PATCH, DELETE, HEAD
response = Client.put("https://api.example.com/users/1", %{name: "Alice"})
response = Client.patch("https://api.example.com/users/1", %{name: "Alice"})
response = Client.delete("https://api.example.com/users/1")
response = Client.head("https://api.example.com/ping")

With Options

# Query string parameters
Client.get("https://api.example.com/users", query: %{page: 2, per_page: 25})

# Custom headers
Client.get("https://api.example.com/users", headers: %{"X-Custom-Header" => "value"})

# Request timeout in milliseconds (default: 30 000)
Client.get("https://api.example.com/slow", timeout: 60_000)

# Raise an error if the response is not 2xx
Client.get("https://api.example.com/users", throw: true)

Fluent Builder

Build a request by chaining modifier functions onto a client struct, then calling send/4:

Client.accept_json()
|> Client.with_token("my-api-token")
|> Client.send(:post, "https://api.example.com/users", body: %{name: "Alice"})

Builder Methods

# Start a fresh client
client = Client.new()

# Accept JSON (sets Accept and Content-Type to application/json)
client = Client.accept_json()
client = Client.accept_json(client)

# Attach custom headers
client = Client.with_headers(%{"X-App-Id" => "my-app"})
client = Client.with_headers(client, %{"X-App-Id" => "my-app"})

# Attach a Bearer token (or any scheme)
client = Client.with_token("my-token")
client = Client.with_token(client, "my-token")
client = Client.with_token(client, "my-api-key", "Basic")

# Dispatch the request
response = Client.send(client, :get, "https://api.example.com/users")
response = Client.send(client, :post, "https://api.example.com/users", body: %{name: "Alice"})

Headers set on the builder are merged with any headers passed in the send/4 options. Per-call headers take precedence.


Working with Responses

Every request returns a plain map with :status, :headers, and :body keys.

response = Client.get("https://api.example.com/users")

response.status   # => 200
response.headers  # => %{"content-type" => "application/json", …}
response.body     # => "{\"data\": [{…}]}"

Decoding JSON

response = Client.get("https://api.example.com/users") |> Client.json()
response.body  # => %{"data" => [%{"id" => 1, "name" => "Alice"}]}

Status Helpers

Client.successful?(response)    # true if 200–299
Client.redirect?(response)      # true if 300–399
Client.client_error?(response)  # true if 400–499
Client.server_error?(response)  # true if 500+

Request Body Encoding

Body type Encoding
Binary string Sent as-is
Map (default) Encoded as JSON (application/json)
Map with Content-Type: application/x-www-form-urlencoded URL-encoded form data
IO list Converted to binary and sent as-is
# JSON body (default for maps)
Client.post("https://api.example.com/users", %{name: "Alice"})

# Form-encoded body
Client.with_headers(%{"Content-Type" => "application/x-www-form-urlencoded"})
|> Client.send(:post, "https://api.example.com/form", body: %{name: "Alice"})

Testing: Faking and Stubbing

Activating the Fake

Call Client.fake() before the code under test. All subsequent requests are intercepted in the current process and never reach the network.

Client.fake()

Stubbing Responses

Register URL patterns with Client.stub/2. Patterns support * wildcards.

# Exact URL match
Client.stub("https://api.test/users", %{status: 200, body: [%{id: 1}]})

# Wildcard match
Client.stub("https://api.test/*", %{status: 200, body: %{"ok" => true}})

# Return a plain string body
Client.stub("https://api.test/ping", "pong")

# Custom status code
Client.stub("https://api.test/not-found", %{status: 404, body: %{"message" => "Not found"}})

If no stub matches the requested URL, the fake returns a 200 response with an empty body.

Asserting Requests Were Sent

# Returns true if any recorded request matches the predicate
Client.assert_sent(fn req -> req.method == :post end)
Client.assert_sent(fn req -> String.contains?(req.url, "/users") end)
Client.assert_sent(fn req ->
  req.method == :post and req.url == "https://api.test/users"
end)

Inspecting Sent Requests

Client.sent()
# => [
#   %{method: :get, url: "https://api.test/users", headers: %{}, body: ""},
#   %{method: :post, url: "https://api.test/users", headers: %{…}, body: %{name: "Alice"}}
# ]

Each entry in sent() contains :method, :url, :headers (map), and :body (the original pre-encoded body).


Helper Access

The http/0 Helpers returns Laravex.Http.Client as a shortcut:

import Laravex.Support.Helpers

http().get("https://api.example.com/users") |> http().json()

See Also

Clone this wiki locally