Name.Name.
+-spec route_patterns(Name) -> Result + when + Name :: atom(), + Result :: {ok, RoutePatterns} | {error, not_found}, + RoutePatterns :: erf:route_patterns().+ +
Name.
+ Design your API using OpenAPI 3.0. For example: users.openapi.json.
Add erf as a dependency in your rebar3 project.
{deps, [
- {erf, {git, "git@github.com:nomasystems/erf.git", {branch, "main"}}}
-]}.Implement a callback module for your API. A hypothetical example for users.openapi.json would be users_callback.erl.
%% An <code>erf</code> callback for the users REST API.
--module(users_callback).
+Design your API using OpenAPI 3.0. For example: users.openapi.json.
Add erf as a dependency in your rebar3 project.
{deps, [
+ {erf, {git, "git@github.com:nomasystems/erf.git", {branch, "main"}}}
+]}.
Implement a callback module for your API. A hypothetical example for users.openapi.json would be users_callback.erl.
%% An <code>erf</code> callback for the users REST API.
+-module(users_callback).
%%% EXTERNAL EXPORTS
--export([
+-export([
create_user/1,
get_user/1,
delete_user/1
-]).
+]).
%%%-------------------------------------------------------
%%% EXTERNAL EXPORTS
%%%-------------------------------------------------------
-create_user(#{body := Body} = _Request) ->
- Id = base64:encode(crypto:strong_rand_bytes(16)),
- ets:insert(users, {Id, Body#{<<"id">> => Id}}),
- {201, [], Body#{<<"id">> => Id}}.
-
-get_user(#{path_parameters := PathParameters} = _Request) ->
- Id = proplists:get_value(<<"userId">>, PathParameters),
- case ets:lookup(users, Id) of
- [] ->
- {404, [], #{
+create_user(#{body := Body} = _Request) ->
+ Id = base64:encode(crypto:strong_rand_bytes(16)),
+ ets:insert(users, {Id, Body#{<<"id">> => Id}}),
+ {201, [], Body#{<<"id">> => Id}}.
+
+get_user(#{path_parameters := PathParameters} = _Request) ->
+ Id = proplists:get_value(<<"userId">>, PathParameters),
+ case ets:lookup(users, Id) of
+ [] ->
+ {404, [], #{
<<"message">> =>
<<"User ", Id/binary, " not found">>
- }};
- [{Id, User}] ->
- {200, [], User}
+ }};
+ [{Id, User}] ->
+ {200, [], User}
end.
-delete_user(#{path_parameters := PathParameters} = _Request) ->
- Id = proplists:get_value(<<"userId">>, PathParameters),
- case ets:lookup(users, Id) of
- [] ->
- {404, [], #{
+delete_user(#{path_parameters := PathParameters} = _Request) ->
+ Id = proplists:get_value(<<"userId">>, PathParameters),
+ case ets:lookup(users, Id) of
+ [] ->
+ {404, [], #{
<<"message">> =>
<<"User ", Id/binary, " not found">>
- }};
- [_User] ->
- ets:delete(users, Id),
- {204, [], #{<<"id">> => Id}}
- end.
Start an erf instance using the erf:start_link/1 function under the supervisor of your application. For example:
-module(users_sup).
+ }};
+ [_User] ->
+ ets:delete(users, Id),
+ {204, [], #{<<"id">> => Id}}
+ end.
Start an erf instance using the erf:start_link/1 function under the supervisor of your application. For example:
-module(users_sup).
%%% BEHAVIOURS
--behaviour(supervisor).
+-behaviour(supervisor).
%%% START/STOP EXPORTS
--export([start_link/0]).
+-export([start_link/0]).
%%% INTERNAL EXPORTS
--export([init/1]).
+-export([init/1]).
%%%-------------------------------------------------------
%%% START/STOP EXPORTS
%%%-------------------------------------------------------
-start_link() ->
- supervisor:start_link({local, ?MODULE}, ?MODULE, []).
+start_link() ->
+ supervisor:start_link({local, ?MODULE}, ?MODULE, []).
%%%-------------------------------------------------------
%%% INTERNAL EXPORTS
%%%-------------------------------------------------------
-init([]) ->
+init([]) ->
% Users storage
- ets:new(users, [public, named_table]),
- UsersAPIConf = #{
+ ets:new(users, [public, named_table]),
+ UsersAPIConf = #{
spec_path => <<"priv/users.openapi.json">>,
callback => users_callback,
- preprocess_middlewares => [users_preprocess],
- postprocess_middlewares => [users_postprocess],
+ preprocess_middlewares => [users_preprocess],
+ postprocess_middlewares => [users_postprocess],
port => 8080
- },
- UsersChildSpec = {
+ },
+ UsersChildSpec = {
public_api_server,
- {erf, start_link, [UsersAPIConf]},
+ {erf, start_link, [UsersAPIConf]},
permanent,
5000,
worker,
- [erf]
- },
- {ok, {{one_for_one, 5, 10}, [UsersChildSpec]}}.
Notice the configured preprocess and postprocess middlewares. They implement a basic authorization mechanism, short-circuiting the request and returning a 403 HTTP error code if the X-API-KEY: api-key header is missing, and they print in console the time in microseconds that authorized requests take to complete.
Start requesting your service.
$ curl -vvv 'localhost:8080/users' -H 'Content-Type: application/json' -H 'X-API-KEY: api-key' -d '{"username": "foo", "password": "foobar"}'
+ [erf]
+ },
+ {ok, {{one_for_one, 5, 10}, [UsersChildSpec]}}.
Notice the configured preprocess and postprocess middlewares. They implement a basic authorization mechanism, short-circuiting the request and returning a 403 HTTP error code if the X-API-KEY: api-key header is missing, and they print in console the time in microseconds that authorized requests take to complete.
Start requesting your service.
$ curl -vvv 'localhost:8080/users' -H 'Content-Type: application/json' -H 'X-API-KEY: api-key' -d '{"username": "foo", "password": "foobar"}'
* Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> POST /users HTTP/1.1
@@ -245,27 +245,27 @@
erf configuration
erf's main entry point (i.e., the start_link/1 function) receives an API specification, a callback module and a set of optional values that enable its configuration.
The configuration is provided as map with the following type spec:
%%% erf.erl
--type conf() :: #{
- spec_path := binary(),
- callback := module(),
- port => inet:port_number(),
- name => atom(),
- spec_parser => module(),
- preprocess_middlewares => [module()],
- postprocess_middlewares => [module()],
- ssl => boolean(),
- certfile => binary(),
- keyfile => binary(),
- static_routes => [static_route()],
- swagger_ui => boolean(),
- min_acceptors => pos_integer(),
- accept_timeout => pos_integer(),
- request_timeout => pos_integer(),
- header_timeout => pos_integer(),
- body_timeout => pos_integer(),
- max_body_size => pos_integer(),
- log_level => logger:level()
-}.
A detailed description of each parameter can be found in the following list:
spec_path : Path to API specification file.callback: Name of the callback module.port: Port the server will listen to. Defaults to 8080.name: Name under which the server is registered. Defaults to erf.spec_parser: Name of the specification parser module. Defaults to erf_parser_oas_3_0.preprocess_middlewares: List of names of middlewares to be invoked before the request is forwarded to the callback. Defaults to [].postprocess_middlewares: List of names of middlewares to be invoked after the response is returned by the callback. Defaults to [].ssl: Boolean flag that enables/disables SSL. Defaults to false.certfile: Path to the SSL certificate file. Defaults to undefined.keyfile: Path to the SSL key file. Defaults to undefined.static_routes: List of routes that serve static files. Defaults to [].swagger_ui: Boolean flag that enables/disables the Swagger UI. Defaults to false.min_acceptors: Minimum number of acceptor processes. Defaults to 20.accept_timeout: Timeout in ms for accepting an incoming request. Defaults to 10000.request_timeout: Timeout in ms for receiving more packets when waiting for the request line. Defaults to 60000.header_timeout: Timeout in ms for receiving more packets when waiting for the headers. Defaults to 10000.body_timeout: Timeout in ms for receiving more packets when waiting for the body. Defaults to 30000.max_body_size: Maximum size in bytes for the body of allowed received messages. Defaults to 1024000.log_level: Severity associated to logged messages. Defaults to error.
+
-type conf() :: #{
+ spec_path := binary(),
+ callback := module(),
+ port => inet:port_number(),
+ name => atom(),
+ spec_parser => module(),
+ preprocess_middlewares => [module()],
+ postprocess_middlewares => [module()],
+ ssl => boolean(),
+ certfile => binary(),
+ keyfile => binary(),
+ static_routes => [static_route()],
+ swagger_ui => boolean(),
+ min_acceptors => pos_integer(),
+ accept_timeout => pos_integer(),
+ request_timeout => pos_integer(),
+ header_timeout => pos_integer(),
+ body_timeout => pos_integer(),
+ max_body_size => pos_integer(),
+ log_level => logger:level()
+}.
A detailed description of each parameter can be found in the following list:
spec_path : Path to API specification file.callback: Name of the callback module.port: Port the server will listen to. Defaults to 8080.name: Name under which the server is registered. Defaults to erf.spec_parser: Name of the specification parser module. Defaults to erf_parser_oas_3_0.preprocess_middlewares: List of names of middlewares to be invoked before the request is forwarded to the callback. Defaults to [].postprocess_middlewares: List of names of middlewares to be invoked after the response is returned by the callback. Defaults to [].ssl: Boolean flag that enables/disables SSL. Defaults to false.certfile: Path to the SSL certificate file. Defaults to undefined.keyfile: Path to the SSL key file. Defaults to undefined.static_routes: List of routes that serve static files. Defaults to [].swagger_ui: Boolean flag that enables/disables the Swagger UI. Defaults to false.min_acceptors: Minimum number of acceptor processes. Defaults to 20.accept_timeout: Timeout in ms for accepting an incoming request. Defaults to 10000.request_timeout: Timeout in ms for receiving more packets when waiting for the request line. Defaults to 60000.header_timeout: Timeout in ms for receiving more packets when waiting for the headers. Defaults to 10000.body_timeout: Timeout in ms for receiving more packets when waiting for the body. Defaults to 30000.max_body_size: Maximum size in bytes for the body of allowed received messages. Defaults to 1024000.log_level: Severity associated to logged messages. Defaults to error.
@@ -279,27 +279,27 @@
Hot-configuration reloading
The design principles behind erf allow its instances to be reconfigured in runtime with no needed downtime. While not every configuration key is updatable once the server is started (e.g., the port), some interesting features of the framework can be updated on-the-fly.
The following type spec corresponds to the runtime configuration of an erf instance. At the same time, is the type spec of the second argument for the erf:reload/2 function.
%%% erf_conf.erl
--type t() :: #{
- callback => module(),
- log_level => logger:level(),
- preprocess_middlewares => [module()],
- postprocess_middlewares => [module()],
- router => erl_syntax:syntaxTree(), % not manually updatable
- router_mod => module(), % not manually updatable
- spec_path => binary(),
- spec_parser => module(),
- static_routes => [erf:static_route()],
- swagger_ui => boolean()
-}.
NOTE: the router and router_mod keys are not updatable as they are automatically computed when new configuration is provided.
+
-type t() :: #{
+ callback => module(),
+ log_level => logger:level(),
+ preprocess_middlewares => [module()],
+ postprocess_middlewares => [module()],
+ router => erl_syntax:syntaxTree(), % not manually updatable
+ router_mod => module(), % not manually updatable
+ spec_path => binary(),
+ spec_parser => module(),
+ static_routes => [erf:static_route()],
+ swagger_ui => boolean()
+}.NOTE: the
routerandrouter_modkeys are not updatable as they are automatically computed when new configuration is provided.
As shown in erf configuration, the server supports routes that serve static files. The type spec for static routes is the following:
%%% erf.erl
--type static_dir() :: {dir, binary()}.
--type static_file() :: {file, binary()}.
--type static_route() :: {Path :: binary(), Resource :: static_file() | static_dir()}.This feature enables erf to serve a Swagger UI version with your API specification. Just set the swagger_ui flag to true and open your web browser in the server host under the /swagger path.
This feature enables erf to serve a Swagger UI version with your API specification. Just set the swagger_ui flag to true and open your web browser in the server host under the /swagger path.