njord v1.0.2 Njord behaviour

Njord behaviour. This library is a wrapper around HTTPoison to build client REST API libraries as specifications.

defmodule Github do
  use Njord

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

  def valid_username(username) when is_binary(username), do: true
  def valid_username(_), do: false

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

  defget :get_repos,
    [path: "/users/:user",
    arguments: [user: [type: :path_arg,
                       validation: fn x -> valid_username(x) end]]]
end

The previous example generates a module called Github with two functions:

get_repos/1 that receives the user and returns the repositories from that user.
get_repos/2 that receives the user and a list of options. This options are the same options passed to the functions in HTTPoison with the extra option :state. The state can be any Elixir term. This state is used in the functions that process the requests and the response.

The macro defget sends a GET request to the URL. For the other methods use the macro that you need: defget, defpost, defput, defdelete, defhead, defpatch, defoptions

iex(1)> Github.get_repos("alexdesousa")
{:ok, %HTTPoison.Response{...}}

Overriding functions

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

alias HTTPoison.Response

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

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

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

# Processes the response headers.
@spec process_response_headers(name, Response.t, [{binary, binary}], term)
  :: Response.t
    when name: {function_name, arity}, function_name: atom, arity: integer
def process_response_headers(name, response, headers, state)

# Processes the response body.
@spec process_response_body(name, Response.t, String.t, term)
  :: Response.t
    when name: {function_name, arity}, function_name: atom, arity: integer
def process_response_body(name, response, body, state)

# Processes the status code of the request.
@spec process_status_code(name, Response.t, integer, term)
  :: Response.t
    when name: {function_name, arity}, function_name: atom, arity: integer
def process_status_code(name, response, status_code, state)

Summary

Types

method()

t()

Functions

join_query(request, url)

Joins the params from the request as a query to the url

Macros

__using__()

Basic definitions for the behaviour

defdelete(name, options \\ [])

Generates a function to identified by a name call an API with the DELETE method. The list of options is the same as defendpoint/3 macro

defendpoint(name, method, options \\ [])

Generates a function to call an API endpoint

defget(name, options \\ [])

Generates a function to identified by a name call an API with the GET method. The list of options is the same as defendpoint/3 macro

defhead(name, options \\ [])

Generates a function to identified by a name call an API with the HEAD method. The list of options is the same as defendpoint/3 macro

defoptions(name, options \\ [])

Generates a function to identified by a name call an API with the OPTIONS method. The list of options is the same as defendpoint/3 macro

defpatch(name, options \\ [])

Generates a function to identified by a name call an API with the PATCH method. The list of options is the same as defendpoint/3 macro

defpost(name, options \\ [])

Generates a function to identified by a name call an API with the POST method. The list of options is the same as defendpoint/3 macro

defput(name, options \\ [])

Generates a function to identified by a name call an API with the PUT method. The list of options is the same as defendpoint/3 macro

Callbacks

process_body(request, body, state)

Processes the request body. Receives the request, the body and the state. It should return the modified request

process_headers(request, headers, state)

Processes the request headers. Receives the request, the headers and state. It should return the modified request

process_response_body(response, function, body, state)

Processes the response body. Receives the function tuple ({name, arity}), the response, the body and the state

process_response_headers(response, function, headers, state)

Processes the response headers. Receives the function tuple ({name, arity}), the response, the headers, and the state

process_status_code(response, function, status_code, state)

Processes the response status_code. Receives the function tuple ({name, arity}), the response, the status_code and the state

process_url(request, url, state)

Processes the url. Receives the request, the url and the state. It should return the modified request

Types

method ::
  :get |
  :post |
  :put |
  :head |
  :patch |
  :delete |
  :options

t :: %Njord{body: Keyword.t, headers: headers :: list, method: method :: method, params: Keyword.t, url: url :: binary}

Functions

join_query(request, url)

Joins the params from the request as a query to the url.

Macros

__using__()

Basic definitions for the behaviour.

defdelete(name, options \\ [])

Generates a function to identified by a name call an API with the DELETE method. The list of options is the same as defendpoint/3 macro.

defendpoint(name, method, options \\ [])

Generates a function to call an API endpoint.

Args:

name - Name of the endpoint function.
method - Method to be used when doing the request. The possible values for the methods are :get, :post, :put, :head, :patch and :options.
options - List of options:
- :path - Path to the endpoint. Use :<name of the var> to add the value of the variable as a path argument i.e. "/accounts/:login" will expect a variable named login in the endpoint function arguments.
- :protocol - Module where the protocol is defined. By default is the module where this macro is called.
- :arguments - List of arguments of the endpoint function. The arguments are defined as name or {name, options} where name is the name of the function argument and the options is a Keyword list with the following possible values:
- type - Type of the argument. Possible values are :path_arg, :arg or body. By default, arguments are of type :arg.
- validation - Validation function of arity of 1.

The generated function has as many arguments as the :arguments option provided plus an optional list of options:

:params - URI query arguments of the request.
:body - Body of the request.
:headers - Headers of the request.
:state - The state of the request.

defget(name, options \\ [])

Generates a function to identified by a name call an API with the GET method. The list of options is the same as defendpoint/3 macro.

defhead(name, options \\ [])

Generates a function to identified by a name call an API with the HEAD method. The list of options is the same as defendpoint/3 macro.

defoptions(name, options \\ [])

Generates a function to identified by a name call an API with the OPTIONS method. The list of options is the same as defendpoint/3 macro.

defpatch(name, options \\ [])

Generates a function to identified by a name call an API with the PATCH method. The list of options is the same as defendpoint/3 macro.

defpost(name, options \\ [])

Generates a function to identified by a name call an API with the POST method. The list of options is the same as defendpoint/3 macro.

defput(name, options \\ [])

Generates a function to identified by a name call an API with the PUT method. The list of options is the same as defendpoint/3 macro.

Callbacks

process_body(request, body, state)

Specs

process_body(request :: Njord.t, body :: Keyword.t, state :: term) :: Njord.t

Processes the request body. Receives the request, the body and the state. It should return the modified request.

process_headers(request, headers, state)

Specs

process_headers(request :: Njord.t, headers :: list, state :: term) :: Njord.t

Processes the request headers. Receives the request, the headers and state. It should return the modified request.

process_response_body(response, function, body, state)

Specs

process_response_body(response :: HTTPoison.Response.t, function :: {name :: atom, arity :: integer}, body :: term, state :: term) :: Njord.t

Processes the response body. Receives the function tuple ({name, arity}), the response, the body and the state.

process_response_headers(response, function, headers, state)

Specs

process_response_headers(response :: HTTPoison.Response.t, function :: {name :: atom, arity :: integer}, headers :: term, state :: term) :: Njord.t

Processes the response headers. Receives the function tuple ({name, arity}), the response, the headers, and the state.

process_status_code(response, function, status_code, state)

Specs

process_status_code(response :: HTTPoison.Response.t, function :: {name :: atom, arity :: integer}, status_code :: term, state :: term) :: Njord.t

Processes the response status_code. Receives the function tuple ({name, arity}), the response, the status_code and the state.

process_url(request, url, state)

Specs

process_url(request :: Njord.t, url :: binary, state :: term) :: Njord.t

Processes the url. Receives the request, the url and the state. It should return the modified request.