README.md

JSONAPI Elixir

A project that will render your data models into JSONAPI Documents and parse/verify JSONAPI query strings.

JSONAPI Support

This library implements version 1.1 of the JSON:API spec.

• Basic JSONAPI Document encoding
• Basic support for compound documents
• Links
• Relationship links
• Parsing of sort query parameter into Ecto Query order_by
• Parsing and limiting of filter keywords.
• Handling of sparse fieldsets
• Handling of includes
• Handling of pagination
• Handling of top level meta data

Documentation

• Full docs here
• JSON API Spec (v1.1)

Badges

How to use with Phoenix

Installation

Add the following line to your mix.deps file with the desired version to install jsonapi.

defp deps do [
  ...
  {:jsonapi, "~> x.x.x"}
  ...
]

Usage

Simply add use JSONAPI.View either to the top of your view, or to the web.ex view section and add the proper functions to your view like so.

defmodule MyApp.PostView do
  use JSONAPI.View, type: "posts"

  def fields do
    [:text, :body, :excerpt]
  end

  def excerpt(post, _conn) do
    String.slice(post.body, 0..5)
  end

  def meta(data, _conn) do
    # this will add meta to each record
    # To add meta as a top level property, pass as argument to render function (shown below)
    %{meta_text: "meta_#{data[:text]}"}
  end

  def relationships do
    # The post's author will be included by default
    [author: {MyApp.UserView, :include},
     comments: MyApp.CommentView]
  end
end

You can now call render(conn, MyApp.PostView, "show.json", %{data: my_data, meta: meta}) or "index.json" normally.

If you'd like to use this without Phoenix simply use the JSONAPI.View and call JSONAPI.Serializer.serialize(MyApp.PostView, data, conn, meta).

Renaming relationships

If a relationship has a different name in the backend than you would like it to in your API, you can rewrite its name in the JSONAPI.View. You pair the view with the name of the relationship used in the data (e.g. Ecto schema) to achieve this. Note that you can use a triple instead of a pair to add the instruction to always include the relation if desired.

defmodule MyApp.PostView do
  use JSONAPI.View, type: "posts"

  def relationships do
    # The `author` will be exposed as `creator` and the `comments` will be 
    # exposed as `critiques` (for some reason).
    [creator: {:author, MyApp.UserView, :include},
     critiques: {:comments, MyApp.CommentView}]
  end
end

Parsing and validating a JSONAPI Request

In your controller you may add

plug JSONAPI.QueryParser,
  filter: ~w(name),
  sort: ~w(name title inserted_at),
  view: PostView

This will add a JSONAPI.Config struct called jsonapi_query to your conn.assigns. If a user tries to sort, filter, include, or requests an invalid fieldset it will raise a Plug error that shows the proper error message.

The config holds the values parsed into things that are easy to pass into an Ecto query, for example sort=-name will be parsed into sort: [desc: :name] which can be passed directly to the order_by in Ecto.

This sort of behavior is consistent for includes.

The JSONAPI.QueryParser plug also supports sparse fieldsets. Please see its documentation for details.

Camelized or Dasherized Fields

JSONAPI has recommended in the past the use of dashes (-) in place of underscore (_) as a word separator for document member keys. However, as of JSON API Spec (v1.1), it is now recommended that member names are camelCased. This library provides various configuration options for maximum flexibility including serializing outgoing parameters and deserializing incoming parameters.

Transforming fields requires two steps:

1. camelCase outgoing fields requires you to set the :field_transformation configuration option. Example:

   config :jsonapi,
     field_transformation: :camelize # or :dasherize, :camelize_shallow, or :dasherize_shallow

2. Underscoring incoming params (both query and body) requires you add the JSONAPI.UnderscoreParameters Plug to your API's pipeline. This makes it easy to work with changeset data.

   pipeline :api do
     plug JSONAPI.EnsureSpec
     plug JSONAPI.UnderscoreParameters
   end

3. JSONAPI.Deserializer is a plug designed to make a JSON:API resource object more convenient to work with when creating or updating resources. This plug works by taking the resource object format and flattening it into an easier to manipulate Map.

   Note that the deserializer expects the same casing for your outgoing params as your incoming params.

   Your pipeline in a Phoenix app might look something like this:

   pipeline :api do
     plug JSONAPI.EnsureSpec
     plug JSONAPI.Deserializer
     plug JSONAPI.UnderscoreParameters
   end

Spec Enforcement

We include a set of Plugs to make enforcing the JSONAPI spec for requests easy. To add spec enforcement to your application, add JSONAPI.EnsureSpec to your pipeline:

plug JSONAPI.EnsureSpec

Under-the-hood JSONAPI.EnsureSpec relies on four individual plugs:

• JSONAPI.ContentTypeNegotiation — Requires the Content-Type and Accept headers are set correctly.

• JSONAPI.FormatRequired — Verifies that the JSON body matches the expected %{data: %{attributes: attributes}} format.

• JSONAPI.IdRequired — Confirm the id key is present in %{data: data} and that it matches the resource's id in the URI.

• JSONAPI.ResponseContentType — Ensures that you return the correct Content-Type header.

Configuration

config :jsonapi,
  host: "www.someotherhost.com",
  scheme: "https",
  namespace: "/api",
  field_transformation: :underscore,
  remove_links: false,
  json_library: Jason,
  paginator: nil

• host, scheme. By default these are pulled from the conn, but may be overridden.
• namespace. This optional setting can be used to configure the namespace your resources live at (e.g. given "http://example.com/api/cars", "/api" would be the namespace). See also JSONAPI.View for setting on the resource's View itself.
• field_transformation. This option describes how your API's fields word boundaries are marked. JSON API Spec (v1.1) recommends using camelCase (e.g. "favoriteColor": blue). If your API uses camelCase fields, set this value to :camelize. JSON:API v1.0 recommended using a dash (e.g. "favorite-color": blue). If your API uses dashed fields, set this value to :dasherize. If your API uses underscores (e.g. "favorite_color": "red") set to :underscore. To transform only the top-level field keys, use :camelize_shallow or :dasherize_shallow.
• remove_links. links data can optionally be removed from the payload via setting the configuration above to true. Defaults to false.
• json_library. Defaults to Jason.
• paginator. Module implementing pagination links generation. Defaults to nil.

Pagination

Pagination links can be generated by overriding the JSONAPI.View.pagination_links/4 callback of your view and returning a map containing the links.

...

def pagination_links(data, conn, page, options) do
  %{first: nil, last: nil, prev: nil, next: nil}
end
...

Alternatively you can define generic pagination strategies by implementing a module conforming to the JSONAPI.Paginator behavior

defmodule PageBasedPaginator do
  @moduledoc """
  Page based pagination strategy
  """

  @behaviour JSONAPI.Paginator

  @impl true
  def paginate(data, view, conn, page, options) do
    number =
      page
      |> Map.get("page", "0")
      |> String.to_integer()

    size =
      page
      |> Map.get("size", "0")
      |> String.to_integer()

    total_pages = Keyword.get(options, :total_pages, 0)

    %{
      first: view.url_for_pagination(data, conn, Map.put(page, "page", "1")),
      last: view.url_for_pagination(data, conn, Map.put(page, "page", total_pages)),
      next: next_link(data, view, conn, number, size, total_pages),
      prev: previous_link(data, view, conn, number, size)
    }
  end

  defp next_link(data, view, conn, page, size, total_pages)
       when page < total_pages,
       do: view.url_for_pagination(data, conn, %{size: size, page: page + 1})

  defp next_link(_data, _view, _conn, _page, _size, _total_pages),
    do: nil

  defp previous_link(data, view, conn, page, size)
       when page > 1,
       do: view.url_for_pagination(data, conn, %{size: size, page: page - 1})

  defp previous_link(_data, _view, _conn, _page, _size),
    do: nil
end

and configuring it as the global pagination logic in your mix.config

config :jsonapi, :paginator, PageBasedPaginator

or as the view pagination logic when using JSONAPI.View

use JSONAPI.View, paginator: PageBasedPaginator

Links can be generated using the JSONAPI.Config.page information stored in the connection assign jsonapi_query and by passing additional information to the pagination_links/4 callback or your paginator module by passing options from your controller.

Actual pagination is expected to be handled in your application logic and is outside the scope of this library.

Other

• Feel free to make PR's. I will do my best to respond within a day or two.
• If you want to take one of the TODO items just create an issue or PR and let me know so we avoid duplication.
• If you need help, I am on irc and twitter.
• Example project