HTTPEx (HTTPEx v0.2.4)

View Source

HTTPEx provides common functionality to do HTTP calls like GET and POST via a HTTP client (like HTTPoison, Finch etc.).

It adds a couple of additional features on top of a HTTP library:

  • Adds OT tracing
  • Adds a standarized Request, Response and Error struct
  • Switch between different HTTP clients (like HTTPoison, Finch etc.)
  • Adds a standarized response
  • Adds retry mechanism when timeout of connection closed is encountered
  • Adds a stub HTTP client that is able to mock requests for all possibile implementations that use this module

See HTTPEx.TestBackend to see how stubbing out requests and responses work.

Summary

Functions

get(url, options \\ [])

Executes GET request

get_header(request, key)

Gets value of request, response or error headers.

post(url, body, options \\ [])

Executes POST request

request(request)

Executes a Request

to_response(response)
to_response(arg, retries)

Functions

get(url, options \\ [])

@spec get(String.t(), Keyword.t()) ::
  {:ok, HTTPEx.Response.t()} | {:error, HTTPEx.Error.t()}

Executes GET request

Examples

iex> HTTPEx.get("http://www.example.com", backend: MockBackend)
{:ok, %HTTPEx.Response{body: "OK!", client: :httpoison, retries: 1, status: 200, parsed_body: nil, headers: []}}

iex> HTTPEx.get("http://www.example.com", backend: MockBackend, client: :finch)
{:ok, %HTTPEx.Response{body: "OK!", client: :httpoison, retries: 1, status: 200, parsed_body: nil, headers: []}}

iex> HTTPEx.get("http://www.example.com/json", headers: [{"Content-Type", "application/json"}], backend: MockBackend)
{
  :ok,
  %HTTPEx.Response{
    body: "{\"payload\":{\"items\":[1,2,3]}}",
    client: :httpoison,
    headers: [],
    parsed_body: %{"payload" => %{"items" => [1, 2, 3]}},
    retries: 1,
    status: 202
  }
}

iex> HTTPEx.get("http://www.example.com/error", backend: MockBackend)
{
  :error,
  %HTTPEx.Error{
    body: "{\"errors\":[{\"code\":\"invalid_payload\"}]}",
    client: :httpoison,
    headers: [],
    parsed_body: %{"errors" => [%{"code" => "invalid_payload"}]},
    retries: 1,
    status: 422,
    reason: :unprocessable_entity
  }
}

get_header(request, key)

@spec get_header(
  HTTPEx.Request.t() | HTTPEx.Response.t() | HTTPEx.Error.t() | [tuple()],
  String.t()
) ::
  String.t() | nil

Gets value of request, response or error headers.

Examples

iex> HTTPEx.get_header(%Request{method: :get, url: "http://example.com", headers: [{"Content-Type", "application/json"}, {"Secret", "123"}]}, "content-type") "application/json"

iex> HTTPEx.get_header(%Response{headers: [{"Content-Type", "application/json"}, {"Secret", "123"}]}, "Secret") "123"

iex> HTTPEx.get_header(%Response{headers: [{"Content-Type", "application/json"}, {"Secret", "123"}]}, "non-existent-key") nil

post(url, body, options \\ [])

@spec post(
  String.t(),
  iodata()
  | {:stream, Enumerable.t()}
  | {:multipart, Enumerable.t()}
  | {:form, Enumerable.t()}
  | nil,
  Keyword.t()
) :: {:ok, HTTPEx.Response.t()} | {:error, HTTPEx.Error.t()}

Executes POST request

Examples

iex> HTTPEx.post("http://www.example.com", JSON.encode!(%{"data" => true}), backend: MockBackend)
{:ok, %HTTPEx.Response{body: "OK!", client: :httpoison, retries: 1, status: 200, parsed_body: nil, headers: []}}

request(request)

@spec request(HTTPEx.Request.t()) ::
  {:ok, HTTPEx.Response.t()} | {:error, HTTPEx.Error.t()}

Executes a Request

Examples

iex> request = %HTTPEx.Request{
...>   method: :get,
...>   client: :finch,
...>   url: "http://www.example.com",
...>   options: [backend: MockBackend],
...> }
...> HTTPEx.request(request)
{:ok, %HTTPEx.Response{body: "OK!", client: :httpoison, retries: 1, status: 200, parsed_body: nil, headers: []}}

iex> request = %HTTPEx.Request{
...>   method: :post,
...>   body: JSON.encode!(%{"data" => true}),
...>   url: "http://www.example.com/json",
...>   headers:  [{"Content-Type", "application/json"}],
...>   options: [backend: MockBackend],
...> }
...> HTTPEx.request(request)
{
  :ok,
  %HTTPEx.Response{
    body: "{\"payload\":{\"label\":\"ABCD\"}}",
    client: :httpoison,
    headers: [],
    parsed_body: %{"payload" => %{"label" => "ABCD"}},
    retries: 1,
    status: 200
  }
}

to_response(response)

to_response(arg, retries)