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
build_sort(binary, field) View Source
call(conn, opts) View Source
Callback implementation for Plug.call/2
.
get_valid_fields_for_type(map, type) View Source
get_view_for_type(view, type) View Source
handle_include(str, config) View Source
handle_nested_include(key, valid_include, config) View Source
init(opts) View Source
Callback implementation for Plug.init/1
.