jsonapi v0.9.0 JSONAPI.QueryParser View Source

Implements a fully JSONAPI V1 spec for parsing a complex query string and returning elixir datastructures. The purpose is to validate and encode incoming queries and fail quickly.

Primarialy this handles:

This plug works in conjunction with a JSONAPI View as well as some plug defined configuration.

In your controller you may add

plug JSONAPI.QueryParser,
  filter: ~w(title),
  sort: ~w(created_at title),
  view: MyView

If your controller's index function receives a query with params inside those bounds it will build a JSONAPI.Config that has all the validated and parsed fields for your usage. The final configuration will be added to assigns jsonapi_query.

The final output will be a JSONAPI.Config struct and will look similar to like

%JSONAPI.Config{
  view: MyView,
  opts: [view: MyView, sort: ["created_at", "title"], filter: ["title"]],
  sort: [desc: :created_at] # Easily insertable into an ecto order_by,
  filter: [title: "my title"] # Easily reduceable into ecto where clauses
  include: [comments: :user] # Easily insertable into a Repo.preload,
  fields: %{"myview" => [:id, :text], "comment" => [:id, :body],
  page: %JSONAPI.Page{
    limit: limit,
    offset: offset,
    page: page,
    size: size,
    cursor: cursor
  }}
}

The final result should allow you to build a query quickly and with little overhead. You will notice the fields section is a not as easy to work with as the others and that is a result of Ecto not supporting high quality selects quite yet. This is a WIP.

Options

  • :view - The JSONAPI View which is the basis for this plug.
  • :sort - List of atoms which define which fields can be sorted on.
  • :filter - List of atoms which define which fields can be filtered on.

Dasherized Fields

Note that if your API is returning dasherized fields (e.g. "dog-breed": "Corgi") we recommend that you include the JSONAPI.UnderscoreParameters Plug in your API's pipeline. This will underscore fields for easier operations in your code.

For more details please see JSONAPI.UnderscoreParameters.

Link to this section Summary

Link to this section Functions

Link to this function

build_sort(binary, field) View Source

Callback implementation for Plug.call/2.

Link to this function

get_valid_fields_for_type(map, type) View Source

Link to this function

get_view_for_type(view, type) View Source

Link to this function

handle_include(str, config) View Source

Link to this function

handle_nested_include(key, valid_include, config) View Source

Callback implementation for Plug.init/1.

Link to this function

parse_fields(config, map) View Source

Link to this function

parse_filter(config, map) View Source

Link to this function

parse_include(config, include_str) View Source

Link to this function

parse_pagination(config, map) View Source

Link to this function

parse_sort(config, sort_fields) View Source