xrzhao / leptus

Erlang REST framework that runs on top of cowboy

Leptus

Leptus is an Erlang REST framework that runs on top of cowboy.

Leptus aims at simply creating RESTful APIs.

Requirements

• Erlang/OTP R15B or newer
• cowboy
• jiffy or jsx
• msgpack

Installation

Clone it and just run make

OR

If you want to use it as a dependency in your project add the following to your rebar configuration

{deps, [
        ...
        {leptus, ".*", {git, "git://github.com/s1n4/leptus.git", {branch, "master"}}}
       ]}.

NOTE: if you prefer jsx rather than jiffy the environment variable USE_JSX must be set to true when getting dependencies and/or compiling.

i.e.

USE_JSX=true make
# OR
USE_JSX=true rebar get-deps compile

Quick example

-module(hello).
-compile({parse_transform, leptus_pt}).

%% leptus callbacks
-export([init/3]).
-export([get/3]).
-export([terminate/4]).

init(_Route, _Req, State) ->
    {ok, State}.

get("/", _Req, State) ->
    {<<"Hello, leptus!">>, State};
get("/hi/:name", Req, State) ->
    Status = ok,
    Name = leptus_req:param(Req, name),
    Body = [{<<"say">>, <<"Hi">>}, {<<"to">>, Name}],
    {Status, {json, Body}, State}.

terminate(_Reason, _Route, _Req, _State) ->
    ok.

$ erl -pa ebin deps/*/ebin

1> c(hello).
2> leptus:start_listener(http, [{'_', [{hello, undefined_state}]}]).
Leptus started on http://127.0.0.1:8080

$ curl localhost:8080/hi/Leptus
{"say":"Hi","to":"Leptus"}

Features

• Supports GET, PUT, POST and DELETE HTTP methods
• Can respond in plain text, JSON or MessagePack
• Supports basic authentication
• Can be upgraded while it’s running (no stopping is required)
• Supports HTTPS and SPDY
• Provides a simple way for dealing with Cross-Origin Resource Sharing

Documentation

Check out the docs directory.

Support

• Issue tracker
• #leptus IRC channel on Freenode
• leptus mailing-list on Google Groups

License

MIT, see LICENSE file for more details.