Cowboy REST JSON API Guide

Initial Setup

Here is a screencast of this procedure:

Like in the Quick Start we will use rebar3

First let’s start installing the template we will use, this needs to be done only once:

mkdir -p ~/.config/rebar3/templates
git clone ~/.config/rebar3/templates/fn_rest_app

Now we create the folder where our new project will live:

mkdir myrestapp
cd myrestapp

Then we install rebar inside our project folder:

chmod u+x rebar3

We can then create the project using the installed template, change myrestapp for the name of your project but if you do remember to change it in the following commands too:

./rebar3 new fn_rest_app name=myrestapp

We can then build the project:

./rebar3 release

And start it:

./_build/default/rel/myrestapp/bin/myrestapp console

From another shell we can test our API:

curl http://localhost:8080/
curl http://localhost:8080/ -H "Accept: text/plain"
curl http://localhost:8080/ -H "Accept: application/json"

We can open our browser and go to http://localhost:8080/ to see the html version.

You can quit the console by running q(). like this:

(myrestapp@> q().

Adding a Resource

We have our basic REST API running but we want to add a resource, for that we can use another template, the first time we will need to add it to our template directory:

git clone ~/.config/rebar3/templates/fn_rest_resource

After this we can create our new resource, let’s create a user resource:

cd apps/myrestapp/src
rebar3 new fn_rest_resource name=user
cd ../../..

Finally we need to add our resource to the routes of our API, open apps/myrestapp/src/myrestapp_app.fn and change this:

Dispatch = cowboy_router.compile([(`_`, [("/", myrestapp_handler, []) ])

For this:

Dispatch = cowboy_router.compile([(`_`,
                                   [("/", myrestapp_handler, []),
                                    ("/user", user_rest_handler, [])])

Stop the shell if you are running it (call “q().”), build and start it again:

./rebar3 release
./_build/default/rel/myrestapp/bin/myrestapp console

Now we can test our resource from the command line:

curl -X GET http://localhost:8080/user -H "Content-Type: application/json"

curl -X DELETE http://localhost:8080/user -H "Content-Type: application/json"

curl -X POST http://localhost:8080/user -H "Content-Type: application/json" -d "[1,2,3]"

curl -X PUT http://localhost:8080/user -H "Content-Type: application/json" -d "[1,2,3]"

Changing the Configuration

Say we want to change the port where the app is running, how do we do it?

Well, this template has it all covered, we use cuttlefish to handle the configuration.

Open the file at ./_build/default/rel/myrestapp/etc/myrestapp.conf and search for the line that contains “http.port = 8080”,

change the port to something else, like 8081, save and quit.

Now start the server again and look at the logs while it starts, it should print a line like this:

[info] App myrestapp started at port 8081

this configuration file and its parser are generated from the file at config/config.schema, read the cuttlefish documentation for more information, but as a start you can modify/remove the existing fields that are there as examples.