HttpBuilder v0.4.1 HttpBuilder View Source
HttpBuilder is a library that provides a DSL for composable HTTP Requests.
Each method provided builds and updates a HTTPBuilder.Request object,
until passed into send, which calls the adapter to invoke the request.
Example
Here’s an example of a complete request chain:
HTTPBuilder.new()
|> with_adapter(HttpBuilder.Adapters.HTTPoison)
|> post("http://httparrot.com/post/1")
|> with_headers(%{"Authorization" => "Bearer token"})
|> with_json_parser(Jason)
|> with_json_body(%{"test" => "true"})
|> with_request_timeout(10_000)
|> with_receive_timeout(5_000)
|> send() # kicks off the request.This can also be broken down into composable parts, allowing you to easily write declarative pipelines for your API calls.
defmodule MyAPIClient do
alias HttpBuilder.Adapters
@adapter Application.get_env(:my_api_client, :client, Adapters.HTTPoison)
def client do
HTTPBuilder.new()
|> with_adapter()
|> with_host("http://httparrot.com/")
|> with_headers(%{"Authorization" => "Bearer token"})
|> with_request_timeout(10_000)
|> with_receive_timeout(5_000)
end
def create(params) do
client()
|> post("/new")
|> with_json_body(params)
|> send()
end
def update(id, params) do
client()
|> put("/item/#{id}")
|> with_json_body(params)
|> send()
end
def list(limit, offset) do
client()
|> get("/items")
|> with_query_params(%{"limit" => limit, "offset" => offset})
|> send()
end
def delete(id) do
client()
|> delete("/item/#{id}")
|> send()
end
endSometimes, you don’t want to make a call against a service. By putting your adapter in your config, you can also easily switch to a test HTTP adapter. By pattern matching against the request object, you can handle exact request scenarios.
defmodule MyAPIClient.TestAdapter do
@behaviour HttpBuilder.Adapter
def send(%{method: :post, path: "/new"}), do: {:ok, new_placeholder_data }
def send(%{method: :get, path: "/items"}), do: {:ok, items_placeholder_data }
# ... other request options.
endLink to this section Summary
Functions
Casts a map of predefined options to a HttpBuilder.Request struct
Sets the connect method on the request
Sets the delete method on the request
Sets the get method on the request
Sets the head method on the request
Creates a new request
Sets the options method on the request
Sets the patch method on the request
Sets the post method on the request
Sets the put method on the request
Executes a request, with the provided adapter
Sets the adapter for the request
Adds a body to the request, with no special notation of type
Marks a body as a file upload
Marks a body as a form-encoded upload
Sets either a list of two-item tuples, or map of headers on the request
Sets the host for the request
Marks a body to be sent as JSON
Sets the json parser for the request. Defaults to Poison if available
Sets additional options for the request that may not be handled by this DSL
Sets either a list of two-item tuples, or map of query params on the request
Sets the receive timeout of the request
Sets the request timeout of the request
Marks a body to be sent as a string
Link to this section Types
Link to this section Functions
Casts a map of predefined options to a HttpBuilder.Request struct.
Sets the connect method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the delete method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the get method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the head method on the request.
Takes an optional path, to be added onto the host of the request.
Creates a new request.
Takes in a host, providing the base path for http requests, and an adapter module to eventually run the request.
Sets the options method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the patch method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the post method on the request.
Takes an optional path, to be added onto the host of the request.
Sets the put method on the request.
Takes an optional path, to be added onto the host of the request.
send(HttpBuilder.HttpRequest.t()) :: {:ok, term()} | {:error, String.t()}
Executes a request, with the provided adapter
Sets the adapter for the request.
Takes an atom, representing a module that conforms to the
HttpBuilder.Adapter behaviour.
Adds a body to the request, with no special notation of type.
This body should be used to handle requests not explicitly covered by HTTPBuilder, or the adapter.
Marks a body as a file upload.
Takes a filepath, and adds a tuple of {:file, filepath} to the body of the
request.
Marks a body as a form-encoded upload.
Takes either a list of two-item tuples, or a map of key-value pairs, and
adds a tuple of {:form, [{"key", "value"} ...]} to the body of the request,
and sets the Content-Type to “application/x-www-form-urlencoded”.
Sets either a list of two-item tuples, or map of headers on the request.
Sets the host for the request.
Can be used for host/path composition to create a client library for an API.
Marks a body to be sent as JSON.
Takes the value passed in, and adds a tuple of {:json, body} to the request,
and adds application/json as Content-Type headers
The adapter will be responsible for encoding the value.
Sets the json parser for the request. Defaults to Poison if available.
Most JSON parsers can be used out of the box. See HttpBuilder.Adapter.JSONParser for adapter details.
Sets additional options for the request that may not be handled by this DSL.
Sets either a list of two-item tuples, or map of query params on the request.
Sets the receive timeout of the request.
A receive timeout is how long until the request recieves a response. A request
has a default value of 5000.
Sets the request timeout of the request.
A request timeout is how long the overall request should take. A request
has a default value of 8000.
Marks a body to be sent as a string.
Takes a string, and adds a tuple of {:string, body} to the request.