Implements validation and parsing of JSON:API requests

This plug handles the specification defined JSON:API request body and query parameters (fields, filter, include, page and sort).

Usage

Add this plug to your plug pipeline/controller like this:

plug JSONAPIPlug.Plug, api: MyApp.API, resource: MyApp.MyResource

If your connection receives a valid JSON:API request this plug will parse it into a JSONAPIPlug struct that will be stored in the Plug.Conn private assign :jsonapi_plug. The final Plug.Conn struct will look similar to the following:

%Plug.Conn{
  ...
  body_params: %{...},
  params: %{"data" => ...},
  private: %{
    ...
    jsonapi_plug: %JSONAPIPlug{
      api: MyApp.API,
      fields: ..., # Defaults to a map of field names by type.
      filter: ..., # Defaults to the query parameter value.
      include: ..., # Defaults to Ecto preload format.
      page: ..., # Defaults to the query parameter value.
      params: ..., # Defaults to Ecto normalized data.
      sort: ..., # Defaults to Ecto order_by format.
      resource: MyApp.MyResource
    }
    ...
  }
  ...
}

You can then use the contents of the struct to load data and call JSONAPIPlug.render/4 or the render function generated by use JSONAPIPlug.Resource to generate responses and render them.

Customizing default behaviour

Body parameters

By default, body parameters are transformed into a format that is compatible with attrs for Ecto.Changeset to perform inserts/updates of Ecto.Schema modules. However, you can transform the JSON:API document in any format you want by writing your own module adopting the JSONAPIPlug.Normalizer behaviour and configuring it through JSONAPIPlug.API configuration.

Query parameters

The JSON:API fields and include query parameters format is defined by the specification. The default implementation accepts the specification format and converts it to data usable as select and preload options to Ecto.Repo functions.

The JSON:API sort query parameter format is not defined, however the specification suggests to use a format for encoding sorting by attribute names with an optional - prefix to invert ordering direction. The default implementation accepts the suggested format and converts it to usable as order_by option to Ecto.Repo functions.

The JSON:API filter and page query parameters format is not defined by the JSON:API specification, therefore the default implementation just copies the value of the query parameters in JSONAPIPlug.

You can transform data in any format you want for any of these parameters by implementing a module adopting the JSONAPIPlug.QueryParser behaviour and configuring it through JSONAPIPlug.API configuration.