# elli - Erlang web server for HTTP APIs

[![][hex badge]][hex package]
[![Documentation][doc badge]][docs]
[![Erlang][erlang badge]][erlang downloads]
[![Travis CI][travis badge]][travis builds]
[![Coverage Status][coveralls badge]][coveralls link]
[![MIT License][license badge]](LICENSE)

[travis builds]:
[travis badge]:
[hex badge]:
[hex package]:
[latest release]:
[erlang badge]:
[erlang downloads]:
[doc badge]:
[docs]: doc/
[coveralls badge]:
[coveralls link]:
[license badge]:

Elli is a webserver you can run inside your Erlang application to
expose an HTTP API. Elli is aimed exclusively at building
high-throughput, low-latency HTTP APIs. If robustness and performance
is more important than general purpose features, then `elli` might be
for you. If you find yourself digging into the implementation of a
webserver, `elli` might be for you. If you're building web services,
not web sites, then `elli` might be for you.

Elli is used in production at Wooga and Game Analytics. Elli requires
OTP 18.0 or newer.

## Installation

To use `elli` you will need a working installation of Erlang 18.0 (or later).

Add `elli` to your application by adding it as a dependency to your

{deps, [
  %% ...
  {elli, "3.0.0"}

Afterwards you can run:

$ rebar3 compile

## Usage
$ rebar3 shell

%% starting elli
1> {ok, Pid} = elli:start_link([{callback, elli_example_callback}, {port, 3000}]).

## Examples

### Callback Module

The best source to learn how to write a callback module
is [src/elli_example_callback.erl](src/elli_example_callback.erl) and
its [generated documentation](doc/ There are a bunch
of examples used in the tests as well as descriptions of all the events.

A minimal callback module could look like this:

-export([handle/2, handle_event/3]).


handle(Req, _Args) ->
    %% Delegate to our handler function
    handle(Req#req.method, elli_request:path(Req), Req).

handle('GET',[<<"hello">>, <<"world">>], _Req) ->
    %% Reply with a normal response. `ok' can be used instead of `200'
    %% to signal success.
    {ok, [], <<"Hello World!">>};

handle(_, _, _Req) ->
    {404, [], <<"Not Found">>}.

%% @doc Handle request events, like request completed, exception
%% thrown, client timeout, etc. Must return `ok'.
handle_event(_Event, _Data, _Args) ->

### Supervisor Childspec

To add `elli` to a supervisor you can use the following example and adapt it to
your needs.


start_link() ->
    supervisor:start_link({local, ?MODULE}, ?MODULE, []).

init([]) ->
    ElliOpts = [{callback, fancyapi_callback}, {port, 3000}],
    ElliSpec = {
        {elli, start_link, [ElliOpts]},

    {ok, { {one_for_one, 5, 10}, [ElliSpec]} }.

## Further Reading

For more information about the features and design philosophy of `elli` check
out the [overview](doc/

## License

Elli is licensed under [The MIT License](LICENSE).