Exling

v0.1.1

Exling v0.1.1 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, k, v)

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

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, client)

Set the client type to handle actual requests. Defaults to :httpoison. Currently only supports :httpoison and :httpoison!. More to come

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

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. Currently only :httpoison and :httpoison! are supported, planning to extend how this works in the future

set(request, k, v)

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

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, k, v)

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

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)

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. 

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

Set the client type to handle actual requests. Defaults to :httpoison. Currently only supports :httpoison and :httpoison!. More to come.

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.

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)

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.

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.

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. Currently only :httpoison and :httpoison! are supported, planning to extend how this works in the future.

{:ok, response} = Exling.new("http://some.api.io") |>
      Exling.get("something")
set(request, k, v)

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