a restful interface for erlang code using webmachine

A RESTful interface for Erlang code

using Webmachine

Copyright 2014 Carl Wright

RESTful interface

• Exposes your app as resources on the Web.

• Resources respond to 6 HTTP methods: GET, HEAD, POST, PUT, DELETE and OPTIONS

HTTP: interface to your erlang app

• Start with an erlang app

• add webmachine code

• Write the dispatch table & web app start

• Write the resource code indicated by the dispatch table

Erlang app

WebmachineHTTP:

A specific application

Webui holds the code to respondto URIs

Webmachine provides anHTTP server to handleURI requests on a specificchannel.

Adding webmachine

• Go to https://github.com/basho/webmachine/wiki

• To see the documentation and to fork a copy of webmachine

• Add it to your erlang application.

The others apps

• To run webmachine, you need the following apps:– mochiweb

• http interaction support library

– crypto• Cryptographic functions to support secure web

– inets• Base webservices (ftp, tftp, http, https, etc.)

Adding to your app definition

• You have a “.rel” to define your application release.

Yes, you need mochiweb, too.

Mochiweb is installed alongwebmachine and your “webui”folder.

Crypto and inets are in the standard erlang libraries.

You just include them inYour application definition.

Release configuration

• Add “webmachine” to your release configuration files for “relx” or “rebar”.

• These are the most common release managers for erlang systems.

Inside your web UI

• OTP folder structure

• ebin holds .app file and compiled binaries

• priv holds the dispatch table.

• src holds the application source code.

Webui.app (in ebin folder)

The src folder

Who does what?

webui_app

webui_sup

webmachinewebui_resource.erl

webui_resource_status.erldispatch

table

A simple dispatch table

1. http://host/device/status/73482720002. http://host {anything else}

Dispatch pattern

{ <pattern>, <resource-mod>, <init-params>}

i.e.

{[“a”], module_a, []}.

matches http://host/a & calls module_a

{[“a”, varname], module_a, []}.

match http://host/a/Carl & calls module_a with “varname” = “Carl”

Left side pattern

• Is a list of any atom, string or star

• Breaks the URL on slashes

• Strings must match the URL contents

• Atoms associate with the value so that you retrieve their value

• Star is “*” and must be the last in the list when present.

A CRUD dispatch

• % Accounts• {["account","add"], webui_resource_account,

[add, [{'POST', <<"accounts">>}]]},• {["account","delete",id], webui_resource_account,

[delete, [{'POST', <<"accounts">>}]]},• {["account","edit",id], webui_resource_account,

[edit, [{'POST', <<"accounts">>}]]},• {["accounts"], webui_resource_account,

[account_many,[{'GET', <<"accounts">>}]]},• {["json","accounts"], webui_resource_account,

[accounts, [{'GET', <<"accounts">>}]]},

A real resource function

How does a resource function wire up to the web?

• There is a mapping between 30+ functions that you can put in a resource module.

• They map to states in the HTTP state machine that webmachine implements.

Resource functions

• resource_exists• service_available• allowed_methods• content_types_provid

ed• etcetera

• These functions all have default values when absent.

• You only write functions when you needs something more.

content_types_provided

• This function defines the types of content that the module can provide.

• It defaults to [{“text/html”,to_html}] .

• to_html is function name that creates the results.

• You might want this to return [{“text/html”,to_html}, {“json”,to_json}]

A real resource function

Actual results

Questions?