http_client v0.1.2 Client

The client module contains two functions of note, do_request/6 and do_request!/6 which perform HTTP actions as well as encoding and decoding data and setting headers involved in the request.

Actions

Actions are the part that actually make the HTTP Request, if that is what you choose to do with this library. It is failry generic. Some actions are provided.

Provided Actions

The provided actions are all simple wrappers around HTTPoison to make the arguments resemble what the callback requires in do_request/6 and do_request!/6

Summary

Functions

delete(href, payload, headers)
delete!(href, payload, headers)
do_request(href, payload, headers, encoder, decoder, action)

Sequences calls to encoder, action, and decoder to perform HTTPoison requests.

It is important to understand how this client works in order to properly use it. It provides two implementations of a single function do_request/6, which takes the arguments explained below:

Argumentdescription
hrefThe URL of the resource to be queried
payloadA Map, Struct, or List to be sent to the server
headersThe headers to be sent with the query
encoderThis is an encoder from the Client package, a list of encoders is provided below
decoderThis is a decoder from the Client package, a list of decoders is proved below
actionThis is an HTTPoison verb. Usage defined below

Notes

When using do_request/6, your actions all need to return a tuple of the format {:ok, data} or {:error, reason}, any other formats will not be properly handled by do_request/6.

Examples

data = Client.do_request(
  "https://httpbin.org/post",
  %{"key" => "value", "key2" => ["value1", "value2"]},
  %{"Header" => "Header/Value"},
  Client.Encoders.JSON,
  Client.Decoders.JSON,
  &Client.post(&1, &2, &3)
)

assert data == {
  :ok,
  %{
    "args" => %{},
    "data" => "{\"key2\":[\"value1\",\"value2\"],\"key\":\"value\"}",
    "files" => %{},
    "form" => %{},
    "headers" => %{
      "Accept" => "application/json",
      "Content-Length" => "42",
      "Content-Type" => "application/json",
      "Header" => "Header/Value",
      "Host" => "httpbin.org",
      "User-Agent" => "hackney/1.6.1"
    },
    "json" => %{
      "key" => "value",
      "key2" => ["value1", "value2"]
    },
    "origin" => "127.0.0.1",
    "url" => "https://httpbin.org/post"
  }
}

iex> Client.do_request("a.com", %{"key" => "value"}, %{}, Client.Encoders.JSON, Client.Decoders.JSON, fn _href, payload, _headers -> {:ok, %HTTPoison.Response{status_code: 200, body: payload}} end)
{:ok, %{"key" => "value"}}
do_request!(href, payload, headers, encoder, decoder, action)

Aggressive version of do_request/6. Aggressive means raising errors rather than returning error structs.

Notes

When using do_request!/6, your actions must all return data directly, outside of the tuple used in the safer version. The reason for this is we expect errors in this case to be raised rather than returned.

Examples

iex> Client.do_request!("a.com", %{"key" => "value"}, %{}, Client.Encoders.JSON, Client.Decoders.JSON, fn _href, payload, _headers -> %HTTPoison.Response{status_code: 200, body: payload} end)
%{"key" => "value"}
get(href, payload, headers)
get!(href, payload, headers)
patch(href, payload, headers)
patch!(href, payload, headers)
post(href, payload, headers)
post!(href, payload, headers)
put(href, payload, headers)
put!(href, payload, headers)