A rebar3 Cowboy REST app and a template

1.1   More information and help

The framework for REST handlers used by Cowboy and Webmachine (and other Erlang Web frameworks?) are very similar. So, the documentation on Webmachine may be helpful with Cowboy REST, also. You can find help with Webmachine here: https://en.wikiversity.org/wiki/Web_Development_with_Webmachine_for_Erlang

1.2   Supporting files

The files of interest for this discussion are in the following archive: test07a_source.zip

This archive contains:

• rebar.config -- A rebar3 configuration file.

-config/sys.config -- A configuration file. You can place values that you want globally available in your application here. See Additional configuration for more information.

• config/vm.args

• vim_cowboy_rest_template -- A template or skeleton file for the Vim text editor. (see below)

• apps/test07a/src/test07a.app.src -- A configuration file for this application. I've added cowboy, sha3, hex (used by sha3), and jiffy (JSON support) as dependencies.

• vim_cowboy_rest_template -- This template can be copied into your src/ directory and renamed as your <my_handler>.erl REST handler module, or, more conveniently, it is intended be inserted into a file with the vim text editor. You can also find this file in a fork of the Vim Erlang Skeletons Github repository here: https://github.com/dkuhlman/vim-erlang-skeletons. And, the original repository from which this one was forked, is here: https://github.com/vim-erlang/vim-erlang-skeletons. In order to use it in Vim, you will need to install it in your .vim directory. For example, if you use the pathogen package manager for Vim, you can do:

  $ cd ~/.vim/bundle
  $ git clone https://github.com/dkuhlman/vim-erlang-skeletons
  

  Also see The Cowboy REST handler template elsewhere in this document.

2.1   Recompiling and reloading

Note: I had problems with the methods in this section, so you will need to experiment with them yourself.

If you started your release with rebar3 shell, then you can quickly recompile any changed files and reload them without leaving the shell:

> r3:do(compile).

As an alternative, there is also the rebar3_auto plugin. Put this in your ~/.config/rebar3/rebar.config config file:

{plugins, [rebar3_auto]}.

In order for the above to work, you might need to install inotify-tools, which on Linux, you can do with apt-get or aptitude.

More information is here: https://www.rebar3.org/docs/using-available-plugins#auto-compile-and-load

2.2   A note on dependencies

You might want to consider doing:

$ rebar3 update

After doing so, you might be able to refer to dependencies, in rebar.config, more briefly. For example:

{deps, [
        cowboy,
        jiffy,
        sha3
       ]}.

I say "might be able to", because I'm not sure about which version this will download. I suspect that it is the latest version referred to in the rebar3 package index. You can display that package index by running the following:

$ rebar3 pkgs

2.3   Additional configuration

You can specify globally available values in config/sys.config. For example, in the example application we are discussing, we need the name and location of a DETS data file:

[
 { test07, [
        {data_file_name,
         "/path/to/directory/containing/test07/Data/test07_data01.dets"}
       ]},
 { test07a, [
        {data_file_name,
         "/path/to/directory/containing/test07/Data/test07a_data01.dets"}
       ]}
].

Then you can obtain the value associated with a name with something like the following:

{ok, DataFileName} = application:get_env(data_file_name),

You can find more information about configuration here: http://erlang.org/doc/man/config.html, and here: http://erlang.org/doc/design_principles/applications.html.

If you generated an additional application, then you may need to do some configuration in the .app.src file for that application. For example, in apps/test07a/src/test07a.app.src, I added additional applications:

{application, test07a,
 [{description, "An OTP application"},
  {vsn, "0.1.0"},
  {registered, []},
  {mod, { test07a_app, []}},
  {applications,
   [kernel,
    stdlib,
    cowboy,
    sha3,
    hex,
    jiffy
   ]},
  {env,[]},
  {modules, []},

  {maintainers, []},
  {licenses, []},
  {links, []}
 ]}.

3.1   The application start-up

In the app module (test07/apps/test07a/src/test07a_app.erl, in our example), we need to do the following:

• Define the routes, i.e. the paths that the client will place on any request URL along with the module that will handle the request with that path.
• Start any additional processes -- In this example, we start a data base server that has been implemented with the gen_server behavior.
• Start the supervisor for application itself.

Here is an example of that code:

-module(test07a_app).
-behaviour(application).
-export([start/2, stop/1]).

start(_Type, _Args) ->
    Dispatch = cowboy_router:compile([
        {'_',
         [
          {"/docs/get/:doc_id", test07a_handler, [{op, get}]},
          {"/docs/list", test07a_handler, [{op, list}]},
          {"/docs/create", test07a_handler, [{op, create}]},
          {"/docs/update/:doc_id", test07a_handler, [{op, update}]},
          {"/docs/delete/:doc_id", test07a_handler, [{op, delete}]},
          {"/docs/help", test07a_handler, [{op, help}]},
          {"/docs", test07a_handler, [{op, help}]}
         ]}
                                     ]),
    {ok, _} = cowboy:start_clear(test07a_http_listener, 100,
                                 [{port, 8002}],
                                 #{env => #{dispatch => Dispatch}}
                                ),
    db_sup:start_link(),
    test07a_sup:start_link().

stop(_State) ->
    ok.

Notes:

• The above routes the URL/path http://somehost:8002/list to the handler module test07a_handler.erl, and passes the options [{op, list}] to the init/2 function.

• In a similar way, it routes the path /docs/get/some_id, to module test07a_handler.erl where we can capture the doc_id, with the following:

  RecordId = cowboy_req:binding(doc_id, Req),
  

• We can capture those options in function init/2, and pass them to other callback functions called during request processing with the following:

  -record(state, {op, response}).
  
  init(Req, Opts) ->
      [{op, Op} | _] = Opts,
      State = #state{op=Op, response=none},
      {cowboy_rest, Req, State}.
  

3.2   The REST handler

In the REST handler module (apps/test07a/src/test07a_handler.erl in our example) we need to (1) tell cowboy that this is a REST module and (2) implement various callbacks needed to handle requests in the way we need them handled.

We handle the first requirement by returning cowboy_rest from our init function:

-record(state, {op, response}).

init(Req, Opts) ->
    [{op, Op} | _] = Opts,
    State = #state{op=Op, response=none},
    {cowboy_rest, Req, State}.

We handle the second requirement by (1) initializing our handler module with the handler template (vim_cowboy_rest_template) and then (2) uncommenting and implementing any callbacks whose default implementations do not fit our needs, and (3) add additional callback functions for each content type you intend to deliver (e.g. in response to GET requests) and each content type you intend to accept (e.g. in response to PUT and POST requests)..

$ cd ~/.vim/bundle
$ git clone https://github.com/dkuhlman/vim-erlang-skeletons.git
$ cd /path/to/myapp
$ vim apps/myapp/src/myapp_handler.erl

content_types_accepted(Req, State) ->
    Value = [
             {<<"application/x-www-form-urlencoded">>, from_json}
            ],
    {Value, Req, State}.

content_types_provided(Req, State) ->
    Value = [
             {{ <<"application">>, <<"json">>, '*'}, to_json}
            ],
    {Value, Req, State}.