njord v1.0.0 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

Functions

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

Macros

Basic definitions for the behaviour

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

Generates a function to call an API endpoint

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

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

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

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

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

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

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

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

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

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

Processes the response status_code. Receives the function tuple ({name, arity}), the response, the status_code and the 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.