njord v1.0.1 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 inHTTPoison
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
Functions
Macros
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.
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 namedlogin
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 asname
or{name, options}
wherename
is the name of the function argument and theoptions
is aKeyword
list with the following possible values:type
- Type of the argument. Possible values are:path_arg
,:arg
orbody
. 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.
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
.
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
.
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
.
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
.