Provides helper functions that allow for quick, one-off HTTP requests. To build composable requests, see the HTTPipe.Conn module.

The functions in this module are designed to provide a (somewhat) parity interface with HTTPoison and HTTPotion. Each major HTTP method has its own function that you can call. For example, to perform an HTTP GET request, it is as simple as:

{:ok, conn} = HTTPipe.get("https://httpbin.org/get")

See the note about configuring an adapter in the README.

The conn that is captured in the above statement is an HTTPipe.Conn struct. All the functions in the module have a return signature of {:ok, Conn.t} | {:error, Conn.t} except for trailing bang (e.g., get!) functions which have a return signature of Conn.t | no_return–anything that would have resulted in an {:error, Conn.t} response before will instead raise the appropriate exception.

If you are coming from HTTPoison or HTTPotion, it is important to note that this library does not return a Response or ErrorResponse struct. This library returns the Conn.t struct which encapsulates the entire transaction. If an error occured, the Conn.t struct returned will include the exception under the :error key.

For a slightly more complicated example, let’s try handling the response. httpbin returns its results as JSON, so for this example, we’ll assume you have the Poison library. The /get path will return the IP address of the client under the "origin" key.

with {:ok, %{response: %{body: body}}} <- HTTPipe.get("https://httpbin.org/get"),
     {:ok, decoded_body} <- Poison.decode(body),
  do: Map.get(decoded_body, "origin")

Headers

Each of the functions in this module allow for custom headers to be passed as a map of the form %{String.t => String.t}. If the function accepts a body, the headers can be passed as the third parameter; otherwise the headers can be passed as the second parameter. By default, an empty map will be passed. For example, let’s set the "Accept" header:

HTTPipe.get("https://httpbin.org/get", %{"Accept" => "application/xml"})

For more information, see the type documentation for HTTPipe.Request.headers.

Body

If the function accepts a body, it will be the second parameter to the function. The body can be passed either as nil, a String.t, or a special tuple that will be processed before executing the connection. For example, to send URL encoded form data, you can use the {:form, data} tuple. The data should be a Keyword.t list no more than one level deep.

post_body = {:form, [name: "HTTPipe", language: "Elixir"]}

HTTPipe.post("https://httpbin.org/post", post_body)

Based on the above connection, the server will receive the following body:

name=HTTPipe&language=Elixir

For more information, see the type documentation for HTTPipe.Request.body.

Options

The final parameter of every function in this module is a keyword list of options. The following options are available:

:adapter

You can use this key to modify the adapter used for a specific connection. For example:

httpc_adapter = HTTPipe.Adapters.HTTPC

# Uses :default adapter
{:ok, conn} = HTTPipe.get("https://httpbin.org/get", %{})
# Uses HTTPC Adapter
{:ok, conn} = HTTPipe.get("https://httpbin.org/get", %{}, [adapter: httpc_adapter])

:adapter_options

The :adapter_options key will be passed directly to the adapter. The adapter you choose should document the options that can be passed in here.

:params

This is a keyword list of query parameters to be appended to the URL you specified. The list should be no deeper than a single key-value pair. This option is primarily to provide compatiability with HTTPoison/HTTPotion. For example:

params = [q: "HTTPipe adapter", language: "elixir"]

{:ok, conn} = HTTPipe.get("https://httpbin.org/get", %{}, [params: params])

The server will receive the following URL request:

https://httpbin.org/get?q=HTTPipe+adapter&language=elixir

Further Testing

If you want to try out the functions more, you can use RequestBin to see how these requests are made to the server. RequestBin gives you a unique, disposable URL which you can send requests to. The requests will then be displayed on the dashboard. For example, let’s try posting to a RequestBin:

url = "http://requestb.in/15mo0ew1"
post_body = {:form, [test_param: "test value"]}
headers = %{"content-type" => "application/x-www-form-urlencoded"}

HTTPipe.post(url, post_body, headers)