Njord

Njörðr, god of the wind and the sea.

This library is a wrapper over HTTPoison to build client APIs. It provides a series of macros that make easy to write a REST API client specification while generating the corresponding functions of the API. Relies on HTTPoison to do the actual request. To define a custom API specification just use Njord.Api module as base.

defmodule Github do
  use Njord.Api
  alias Njord.Api.Request, as: Request

  @url "https://api.github.com"

  def process_url(request, path, _state) do
    %Request{request | url: @url <> path}
  end

  defget :get_repos,
    path: "/users/:username",
    args: [:username]
end

The above example shows how to create the functions get_repos/1 and get_repos/2 (this one receives a list of options for HTTPoison) for the endpoint GET https://api.github.com/users/<username>.

iex(1)> alias HTTPoison.Response, as: Response
iex(2)> Github.get_repos("alexdesousa")
{:ok, %HTTPoison.Response{...}}
iex(3)> Github.get_repos("alexdesousa", stream_to: self())
{:ok, %HTTPoison.AsyncResponse{...}}
iex(4)> flush
%HTTPoison.AsyncStatus{...}
%HTTPoison.AsyncHeaders{...}
%HTTPoison.AsyncChunk{...}
...
%HTTPoison.AsyncChunk{...}
%HTTPoison.AsyncEnd{...}

Overriding functions

Like HTTPoison, Njord.Api defines the following list of functions, all of which can be overriden:

# Processes the endpoint URL after the substitutions.
@spec process_url(Njord.Api.Request.t, String.t, term)
  :: Njord.Api.Request.t
def process_url(request, url, state)

# Processes the request body.
@spec process_body(Njord.Api.Request.t, term, term)
  :: Njord.Api.Request.t
def process_body(request, body, state)

# Processes the request headers.
@spec process_request(Njord.Api.Request.t, [{binary, binary}], term)
  :: Njord.Api.Request.t
def process_headers(request, headers, state)

# Processes the status code of the request.
@spec process_status_code(Njord.Api.Response.t, int, term)
  :: HTTPoison.Response.t
def process_status_code(response, status_code, state)
      
# Processes the response headers.
@spec process_response_headers(Njord.Api.Response.t,
                               [{binary, binary}],
                               term)
  :: HTTPoison.Response.t
def process_response_headers(response, headers, state)

# Processes the response body.
@spec process_response_body(Njord.Api.Response.t, String.t, term)
  :: HTTPoison.Response.t
def process_response_body(response, body, state)

These functions are executed in the order the were listed.

Options

When generating the specification of the endpoint, there are several options:

• name - Name of the endpoint function.
• method - Method to be used when doing the request.
• options - List of options:
  • :path - Path of the endpoint. Use :<name of the var> to replace information it on the path i.e. "/accounts/:login" will expect a variable named login in the function arguments.
  • :args - Name of the variables of the endpoint function.
  • :protocol - Module where the protocol is defined.
  • :state_getter - Function to get or generate the state of every request.

And when calling the genererated function there are other aditional options:

• :params - Parameters of the HTTP request as a Keyword list.
• :body - Body of the request. If in the definition of the endpoint there is an argument named :body this will have priority over the one in the options.
• :headers- Headers of the request. A list of tuples with the name of the header and its content.
• :state - A state for the process_* functions.
• :state_getter - Function to get or generate the state of the request.

Also any other option available for HTTPoison.

Installation

If available in Hex, the package can be installed as:

• When available in hex Add njord to your list of dependencies in mix.exs:

def deps do
  [{:njord, "~> 0.1.0"}]
end

• If not available in hex:

def deps do
  [{:njord, github: "gmtprime/njord"}]
end

• Ensure njord can be used starting HTTPoison:

def application do
  [applications: [:httpoison]]
end