Liberator

Hex.pm GitHub Workflow Status

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

You can find documentation at https://hexdocs.pm/liberator/.

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!"
end

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
end

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!"}
end

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}
    end
  end
  def handle_ok(conn), do: conn.assigns[:post]
end

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"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/liberator.