JaSerializer

jsonapi.org formatting of Elixir data structures suitable for serialization by libraries such as Poison.

Questions/Help

Please open an issue or message/mention @alanpeabody in the Elixir Slack.

Usage

See documentation on hexdoc for full serialization and usage details.

Installation

Add JaSerializer to your application

mix.deps

defp deps do
  [
    # ...
      {:ja_serializer, "~> x.x.x"}
    # ...
  ]
end

Serializer Behaviour and DSL

defmodule MyApp.ArticleSerializer do
  use JaSerializer

  location "/articles/:id"
  attributes [:title, :tags, :body, :excerpt]

  has_one :author,
    serializer: PersonSerializer,
    include: true,
    field: :authored_by

  has_many :comments,
    links: [
      related: "/articles/:id/comments",
      self: "/articles/:id/relationships/comments"
    ]

  def comments(article, _conn) do
    Comment.for_article(article)
  end

  def excerpt(article, _conn) do
    [first | _ ] = String.split(article.body, ".")
    first
  end
end

Attributes

Attributes are defined as a list in the serializer module. The serializer will use the given atom as the key by default. You can also specify a custom method of attribute retrieval by defining a <attribute_name>/2 method. The method will be passed the struct and the connection.

Relationships

Valid relationships are: has_one, has_many. Use has_one for belongs_to type of relationships. For each relationship, you can define the name and a variety of options. Just like attributes, the serializer will use the given atom to look up the relationship, unless you specify a custom retrieval method OR provide a field option

Relationship options

• serializer - The serializer to use when serializing this resource
• include - boolean - true to always side-load this relationship
• field - custom field to use for relationship retrieval
• links - custom links to use in the relationships hash

Direct Usage of Serializer

MyApp.ArticleSerializer
|> JaSerializer.format(struct, conn)
|> Poison.encode!

Formatting options

The format/4 method is able to take in options that can customize the serialized payload.

Include

By specifying the include option, the serializer will only side-load the relationships specified. This option should be a comma separated list of relationships. Each relationship should be a dot separated path.

Example: include: "author,comments.author"

The format of this string should exactly match the one specified by the JSON-API spec

Note: If specifying the include option, all "default" includes will be ignored, and only the specified relationships included, per spec.

Fields

The fields option satisfies the sparse fieldset portion of the spec. This options should be a map of resource types whose value is a comma separated list of fields to include.

Example: fields: %{"articles" => "title,body", "comments" => "body"}

If you're using Plug, you should be able to call fetch_query_params(conn) and pass the result of conn.query_params["fields"] as this option.

Phoenix Usage

Simply use JaSerializer.PhoenixView in your view (or in the Web module) and define your serializer as above.

The render("index.json-api", data) and render("show.json-api", data) are defined for you. You can just call render as normal from your controller.

By specifying includes when calling the render function, you can override the include: false in the ArticleView.

defmodule PhoenixExample.ArticlesController do
  use PhoenixExample.Web, :controller

  def index(conn, _params) do
    render conn, "index.json-api", data: Repo.all(Article)
  end

  def show(conn, %{"id" => id}) do
    article = Repo.get(Article, id) |> Repo.preload([:comments])
    render conn, "show.json-api", data: article,
      opts: [include: "comments"]
  end

  def create(conn, %{"data" => data}) do
    attrs = JaSerializer.Params.to_attributes(data)
    changeset = Article.changeset(%Article{}, attrs)
    case Repo.insert(changeset) do
      {:ok, article} ->
        conn
        |> put_status(201)
        |> render("show.json-api", data: article)
      {:error, changeset} ->
        conn
        |> put_status(422)
        |> render(:errors, data: changeset)
    end
  end
end

defmodule PhoenixExample.ArticlesView do
  use PhoenixExample.Web, :view
  use JaSerializer.PhoenixView # Or use in web/web.ex

  attributes [:title]

  has_many :comments,
    serializer: PhoenixExample.CommentsView,
    include: false,
    identifiers: :when_included
  #has_many, etc.
end

Configuration

To use the Phoenix accepts plug you must configure Plug to handle the "application/vnd.api+json" mime type and Phoenix to serialize json-api with Poison.

Depending on your version of Plug add the following to config.exs:

Plug ~> "1.2.0"

config :phoenix, :format_encoders,
  "json-api": Poison

config :mime, :types, %{
  "application/vnd.api+json" => ["json-api"]
}

And then re-compile mime: (per: https://hexdocs.pm/mime/MIME.html)

mix deps.clean mime --build
mix deps.get

Plug < "1.2.0"

config :phoenix, :format_encoders,
  "json-api": Poison

config :plug, :mimes, %{
  "application/vnd.api+json" => ["json-api"]
}

And then re-compile plug: (per: https://hexdocs.pm/plug/1.1.3/Plug.MIME.html)

mix deps.clean plug --build
mix deps.get

And then add json api to your plug pipeline.

pipeline :api do
  plug :accepts, ["json-api"]
end

For strict content-type/accept enforcement and to auto add the proper content-type to responses add the JaSerializer.ContentTypeNegotiation plug.

To normalize attributes to underscores include the JaSerializer.Deserializer plug.

pipeline :api do
  plug :accepts, ["json-api"]
  plug JaSerializer.ContentTypeNegotiation
  plug JaSerializer.Deserializer
end

If you're rendering JSON API errors, like 404.json-api, then you must add json-api to the accepts of your render_errors within your existing configuration in config.exs, like so:

config :phoenix, PhoenixExample.Endpoint,
  render_errors: [view: PhoenixExample.ErrorView, accepts: ~w(html json json-api)]

Testing controllers

Set the right headers in setup and when passing parameters to put and post requests, you should pass them as a binary. That is because for map and list parameters, the content-type will be automatically changed to multipart.

defmodule Sample.SomeControllerTest do
  use Sample.ConnCase

  setup %{conn: conn} do
    conn =
      conn
      |> put_req_header("accept", "application/vnd.api+json")
      |> put_req_header("content-type", "application/vnd.api+json")

    {:ok, conn: conn}
  end

  test "create action", %{conn: conn} do
    params = Poison.encode!(%{data: %{attributes: @valid_attrs}})
    conn = post conn, "/some_resource", params

    ...
  end

  ...
end

JSON API Generator

Use our built in generator to get up and running quickly. It uses the same format as the phoenix json generator.

mix ja_serializer.gen.phoenix_api Checkbox checkboxes description:string checked:boolean list_id:references:lists

Want to tweak our templates? Insert your own under 'priv/templates/ja_serializer.gen.phoenix_api/' and we'll use yours instead.

Pagination

JaSerializer provides page based pagination integration with Scrivener or custom pagination by passing your owns links in.

Custom

JaSerializer allows custom pagination via the page option. The page option expects to receive a Map with URL values for first, next, prev, and last.

For example:

page = %{
  first: "http://example.com/api/v1/posts?page[cursor]=1&page[per]=20",
  prev: nil
  next: "http://example.com/api/v1/posts?page[cursor]=20&page[per]=20",
  last: "http://example.com/api/v1/posts?page[cursor]=60&page[per]=20"
}

# Direct call
JaSerializer.format(MySerializer, collection, conn, page: page)

# In Phoenix Controller
render conn, data: collection, opts: [page: page]

Builder

You can build the pagination links with JaSerializer.Builder.PaginationLinks.build/2

Simply pass in the following:

links = JaSerializer.Builder.PaginationLinks.build(%{
  number: 2,
  size: 10,
  total: 20
})

See JaSerializer.Builder.PaginationLinks for how to customize.

Scrivener Integration

If you are using Scrivener for pagination, all you need to do is pass the results of paginate/2 to your serializer.

page = MyRepo.paginate(MyModel, params.page)

# Direct call
JaSerializer.format(MySerializer, page, conn, [])

# In Phoenix controller
render conn, data: page

When integrating with Scrivener, the URLs generated will be based on the Plug.Conn's path. This can be overridden by passing in the page[:base_url] option.

render conn, data: page, opts: [page: [base_url: "http://example.com/foos"]]

You can also configure ja_serializer to use a global default URL base for all links.

config :ja_serializer,
  scrivener_base_url: "http://example.com:4000/v1/"

Note: The resulting URLs will use the JSON-API recommended page query param.

Example URL: http://example.com:4000/v1/posts?page[page]=2&page[page-size]=50

Meta Data

JaSerializer allows adding top level meta information via the meta option. The meta option expects to receive a Map containing the data which will be rendered under the top level meta key.

meta_data = %{
  "key" => "value"
}

# Direct call
JaSerializer.format(MySerializer, data, conn, meta: meta_data)

# In Phoenix controller
render conn, data: data, opts: [meta: meta_data]

Customization

Key Format (for Attribute, Relationship and Query Param)

By default keys are dash-erized as per the jsonapi.org recommendation, but keys can be customized via config.

In your config.exs file:

config :ja_serializer,
  key_format: :underscored

You may also pass custom function for serialization and a second optional one for deserialization. Both accept a single binary argument:

defmodule MyStringModule do
  def camelize(key), do: key #...
  def underscore(key), do: key #...
end

config :ja_serializer,
  key_format: {:custom, MyStringModule, :camelize, :underscore}

If you've already compiled your code, be sure to run mix deps.clean ja_serializer && mix deps.get

Custom Attribute Value Formatters

When serializing attribute values more complex than string, numbers, atoms or list of those things it is recommended to implement a custom formatter.

To implement a custom formatter:

defimpl JaSerializer.Formatter, for: [MyStruct] do
  def format(struct), do: struct
end

Pluralizing All Types By Default

You can opt-in to pluralizing all types for default:

config :ja_serializer,
  pluralize_types: true

Complimentary Libraries

• JaResource - WIP behaviour for creating JSON-API controllers in Phoenix.
• voorhees - Testing tool for JSON API responses
• inquisitor - Composable query builder for Ecto
• scrivener - Ecto pagination

License

JaSerializer source code is released under Apache 2 License. Check LICENSE file for more information.