# Liberator

![GitHub Workflow Status](

An Elixir port of the [Liberator]( Clojure library for building RESTful applications.

You can find documentation at

Liberator allows you to define a controller that adheres to the HTTP spec by providing just a few pieces of information.
For a basic `GET` endpoint, you can define an entire module in five lines of code:

defmodule MyFirstResource do
  use Liberator.Resource

  def available_media_types(_), do: ["text/plain"]
  def handle_ok(_), do: "Hello world!"

A Liberator Resource implements the [Plug]( spec,
so you can forward requests to it in frameworks like Phoenix:

scope "/", MyApp do
  pipe_through [:browser]

  forward "/api/resource", MyFirstResource

Content negotiation and representation becomes easy.
Liberator finds the best media type you support,
and automatically encodes your return value.
JSON is supported out of the box, and any additional types
can be provided in a line of the config.

# in config.exs
config :liberator, media_types: %{
  "application/json" => Jason,
  "application/xml" => MyXmlCodec

# in your main body of code
defmodule MyJsonOrXmlResource do
  use Liberator.Resource

  def available_media_types(_), do: ["application/json", "application/xml"]
  def handle_ok(_), do: %{message: "hi!"}

Your results from questions are aggregated into the `:assigns` map on the conn,
so you don't have to access data more than once.

defmodule MaybeExistingResource do
  use Liberator.Resource

  def exists?(conn) do
    case MyApp.Repo.get(MyApp.Post, conn.params["id"]) do
      nil -> false
      post -> %{post: post}
  def handle_ok(conn), do: conn.assigns[:post]

See more in the [documentation for `Liberator.Resource`](

## Installation

If [available in Hex](, the package can be installed
by adding `liberator` to your list of dependencies in `mix.exs`:

def deps do
    {:liberator, "~> 1.1.0"}

Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at [](