Exling v0.1.2 Exling

Exling is a fluent HTTP request builder and executor for Elixir. It is intended to make it simpler to build HTTP client APIs, but should be handy any time you need to make an HTTP request. It isn’t an HTTTP client library, however, and leaves the actual request and response handling up to already established HTTP libraries.

Exling strives to be a simple, intuitive way to encapsulate API interaction with clear and minimal code that can be built upon and easily extended. Using Elixir’s pipe operator, the developer can clearly define an API request’s URI, headers, body, and method. It makes reasonable assumptions (such as setting the content type for you when possible) while not making it difficult to override these assumptions, and extending the interface should be trivial by manipulating the Exling.Request yourself with your own custom functions.

{:ok, response} = Exling.new |>
      Exling.base("http://some.api.io") |>
      Exling.post("thing") |>
      Exling.body(%{args: "here"}, :json) |>
      Exling.receive()

Summary

Functions

accept(request, type)

Set the HTTP Accept header. Use :json, :form, :xml or :plain, or your custom string if none of those apply

add(request, headers)

Add the key/value pair to the HTTP headers. Additional calls for the same header type are appended

add(request, k, v)

base(request, base_uri)

Set the base URI (or really as much URI information as you want)

body(request, body)

body(request, body, atom)

Set the request body. Use a type option to save yourself the trouble of setting the content type for common values. In the case of :form or :json, your body data should be a map and will automatically be encoded as well. :xml will set the content type but you are on your own for encoding, and if you have other content encoding needs, just use body(my_body) and set the content type yourself with content_type or set

client(request, f)

Set the client module for a predefined request handling backend. Supported options are HTTPoison (default), HTTPotion, :hackney, or :ibrowse. Or, set the client to a one or two arity function for custom impementations. A single arity function will just get the request, a double will also get the options passed to receive. The function will be called with the Exling.Request struct along with any options (see receive). In addition, you can set the default client in the config with config :exling, client: <your client> and avoid this call altogether

content_type(request, type)

Set the HTTP Content-type header. Use :json, :form, :xml or :plain, or your custom string if none of those apply. Note that using body() with the :json, :form, or :xml options will set this for you, but if you need to override it for some reason call this later in the chain

delete(request, path \\ nil)

Set the HTTP method to DELETE. See get for more info and an example

get(request, path \\ nil)

Set the method to GET and (optionally) add to the path. The optional extra path info is handy for REST APIs that may have multiple paths to an object with the final bit being an ID that might change often

head(request, path \\ nil)

Set the HTTP method to HEAD. See get for more info and an example

is_loaded_module(module)

new()

Returns a new Exling.Request

new(base_uri)

Returns a new Exling.Request with base URI configured

options(request, path \\ nil)

Set the HTTP method to OPTIONS. See get for more info and an example

patch(request, path \\ nil)

Set the HTTP method to PATCH. See get for more info and an example

path(request, path)

Set the URI path. Exling will try to figure out slashes for you so a leading slash is optional. Can be called multiple times to append path elements

post(request, path \\ nil)

Set the HTTP method to POST. See get for more info and an example

query(request, query)

query(request, k, v)

Set query params with a map, keyword list, or key and value. Can be called multiple times to append new params

receive(request, options \\ [])

Send the request. The return value is whatever your chosen client implementation returns. See client for supported implementations

set(request, headers)

Sed the key/value pair to the HTTP headers. Additional calls for the same header type will replace any previous entry

set(request, k, v)

Functions

accept(request, type)

Set the HTTP Accept header. Use :json, :form, :xml or :plain, or your custom string if none of those apply.

add(request, headers)

Add the key/value pair to the HTTP headers. Additional calls for the same header type are appended.

add(request, k, v)

base(request, base_uri)

Set the base URI (or really as much URI information as you want).

r = Exling.new |> 
  Exling.base("http://example.com")

r = Exling.new |>
  Exling.base("http://something.else.com/with/more/path")

body(request, body)

body(request, body, atom)

r = Exling.new |>
  Exling.base("http://foo.com") |>
  Exling.post() |>
  Exling.body(%{my: "stuff"}, :json)

client(request, f)

Client implementations are simply modules that use the Exling.Client behaviour, that is, they implement a receive function that simple accepts the request and options, so if none of these defaults work for you you can also implement your own.

content_type(request, type)

r = Exling.new("http://some.api.io")
  Exling.content_type(:plain)
  Exling.body("some string")

delete(request, path \\ nil)

Set the HTTP method to DELETE. See get for more info and an example.

get(request, path \\ nil)

r = Exline.new |>
  Exling.base("http://example.com") |>
  Exling.path("/things") |>
  Exling.get("1")

head(request, path \\ nil)

Set the HTTP method to HEAD. See get for more info and an example.

is_loaded_module(module) (macro)

new()

Returns a new Exling.Request.

# a new, empty request
r = Exling.new

new(base_uri)

Returns a new Exling.Request with base URI configured.

# a request with our base URI already configured
r = Exling.new("http://some.api.io/stuff")

options(request, path \\ nil)

Set the HTTP method to OPTIONS. See get for more info and an example.

patch(request, path \\ nil)

Set the HTTP method to PATCH. See get for more info and an example.

path(request, path)

Set the URI path. Exling will try to figure out slashes for you so a leading slash is optional. Can be called multiple times to append path elements.

# this request points at http://exampl.com/some/path
r = Exling.new |>
  Exling.base("http://example.com") |>
  Exling.path("/some/path")

# and so does this one
r = Exling.new("http://example.com") |>
  Exling.path("some") |>
  Exling.path("path")

# and so does this one (see docs for setting the method)
r = Exling.new("http://example.com") |>
  Exling.path("some")
  Exling.get("path")

post(request, path \\ nil)

Set the HTTP method to POST. See get for more info and an example.

query(request, query)

query(request, k, v)

Set query params with a map, keyword list, or key and value. Can be called multiple times to append new params.

r = Exling.new |>
  Exling.base("http://foo.com") |>
  Exling.query(foo: "bar") |>
  Exling.query(:boo, "far") |>
  Exling.query(Keyword.new([{:b, 1}, {:a, 2}])) |>
  Exling.query(%{and: "more"})

receive(request, options \\ [])

Send the request. The return value is whatever your chosen client implementation returns. See client for supported implementations.

{:ok, response} = Exling.new("http://some.api.io") |>
      Exling.client(HTTPoison)
      Exling.get("something") |>
      Exling.receive()

set(request, headers)

Sed the key/value pair to the HTTP headers. Additional calls for the same header type will replace any previous entry.

set(request, k, v)