JSONAPI Elixir

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

Build Status

JSONAPI Support

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

Documentation

How to use with Phoenix

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

is an example of a basic view. 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).

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_config to your conn.assigns. If a user tries to sort, filter, include, or sparse fieldset an invalid field 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. Sparse fieldsets happen in the view using Map.take but when Ecto gets more complex field selection support we will go further to only query the data we need.

You will need to handle filtering yourself, the filter is just a map with key=value.

Dasherized Fields

JSONAPI now recommends the use of dashes (-) in place of underscore (_) as a word separator. Handling these fields requires two steps:

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

    config :jsonapi,

      field_transformation: :dasherize

  2. Underscoring incoming params (both query and body) requires you add the JSONAPI.UnderscoreParameters Plug to your API's pipeline. Your pipeline in a Phoenix app might look something like this:

    pipeline :api do

      plug(JSONAPI.EnsureSpec)

      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 three individual plugs:

Configuration

config :jsonapi,

  host: "www.someotherhost.com",

  scheme: "https",

  underscore_to_dash: true, # DEPRECATED

  field_transformation: :underscore,

  remove_links: false,

  json_library: Jason

Other