Repository files navigation

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

This library implementsversion 1.1of the JSON:API spec.

• BasicJSONAPI Document encoding
• Basic support forcompound documents
• Links
• Relationship links
• Parsing ofsort query parameter into Ecto Query order_by
• Parsing and limiting offilter keywords.
• Handling ofsparse fieldsets
• Handling ofincludes
• Handling ofpagination
• Handling of top level meta data

• Full docs here
• JSON API Spec (v1.1)

Add the following line to yourmix.deps file with the desired version to installjsonapi.

defpdepsdo[...{:jsonapi,"~> x.x.x"}  ...]

Simply adduse JSONAPI.View either to the top of your view, or to the web.ex view section and add theproper functions to your view like so.

defmoduleMyApp.PostViewdouseJSONAPI.View,type:"posts"deffieldsdo[:text,:body,:excerpt]enddefexcerpt(post,_conn)doString.slice(post.body,0..5)enddefmeta(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]}"}enddefrelationshipsdo# The post's author will be included by default[author:{MyApp.UserView,:include},comments:MyApp.CommentView]endend

You can now callrender(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 theJSONAPI.View and callJSONAPI.Serializer.serialize(MyApp.PostView, data, conn, meta).

If a relationship has a different name in the backend than you would like it to in your API,you can rewrite its name in theJSONAPI.View. You pair the view with the name of the relationshipused in the data (e.g. Ecto schema) to achieve this. Note that you can use a triple insteadof a pair to add the instruction to always include the relation if desired.

defmoduleMyApp.PostViewdouseJSONAPI.View,type:"posts"defrelationshipsdo# The `author` will be exposed as `creator` and the `comments` will be# exposed as `critiques` (for some reason).[creator:{:author,MyApp.UserView,:include},critiques:{:comments,MyApp.CommentView}]endend

In your controller you may add

plugJSONAPI.QueryParser,filter:~w(name),sort:~w(name title inserted_at),view:PostView

This will add aJSONAPI.Config struct calledjsonapi_query to yourconn.assigns. If a user tries to sort, filter, include, or requests aninvalid fieldset it will raise aPlug error that shows the proper errormessage.

The config holds the values parsed into things that are easy to pass into an Ectoquery, for examplesort=-name will be parsed intosort: [desc: :name] whichcan be passed directly to theorder_by in Ecto.

This sort of behavior is consistent for includes.

TheJSONAPI.QueryParser plug also supportssparse fieldsets.Please see its documentation for details.

JSONAPI has recommended in the past the use of dashes (-) in place of underscore (_) as aword separator for document member keys. However, as ofJSON API Spec (v1.1), it is now recommended that member namesare camelCased. This library provides various configuration options for maximum flexibility including serializing outgoing parameters and deserializing incoming parameters.

Transforming fields requires two steps:

1. camelCaseoutgoing fields requires you to set the:field_transformationconfiguration option. Example:

   config:jsonapi,field_transformation::camelize# or :dasherize, :camelize_shallow, or :dasherize_shallow

2. Underscoringincoming params (both query and body) requires you add theJSONAPI.UnderscoreParameters Plug to your API's pipeline. This makes it easy towork with changeset data.

   pipeline:apidoplugJSONAPI.EnsureSpecplugJSONAPI.UnderscoreParametersend

3. JSONAPI.Deserializer is a plug designed to make a JSON:API resource object more convenientto work with when creating or updating resources. This plug works by taking the resourceobject format and flattening it into an easier to manipulate Map.

   Note that the deserializer expects the same casing for youroutgoing params as yourincoming params.

   Your pipeline in a Phoenix app might look something like this:

   pipeline:apidoplugJSONAPI.EnsureSpecplugJSONAPI.DeserializerplugJSONAPI.UnderscoreParametersend

We include a set of Plugs to make enforcing the JSONAPI spec for requests easy. To add spec enforcement to your application, addJSONAPI.EnsureSpec to your pipeline:

plugJSONAPI.EnsureSpec

Under-the-hoodJSONAPI.EnsureSpec relies on four individual plugs:

• JSONAPI.ContentTypeNegotiation — Requires theContent-Type andAccept headers are set correctly.

• JSONAPI.FormatRequired — Verifies that the JSON body matches the expected%{data: %{attributes: attributes}} format.

• JSONAPI.IdRequired — Confirm theid key is present in%{data: data} and that it matches the resource'sid in the URI.

• JSONAPI.ResponseContentType — Ensures that you return the correctContent-Type header.

config:jsonapi,host:"www.someotherhost.com",scheme:"https",namespace:"/api",field_transformation::underscore,remove_links:false,json_library:Jason,paginator:nil

• host,scheme. By default these are pulled from theconn, but may beoverridden.
• namespace. This optional setting can be used to configure the namespaceyour resources live at (e.g. given "http://example.com/api/cars","/api"would be the namespace). See alsoJSONAPI.View for setting on the resource'sView itself.
• field_transformation. This option describes how your API's fields wordboundaries are marked.JSON API Spec (v1.1) recommends using camelCase (e.g."favoriteColor": blue). If your API uses camelCase fields, set this value to:camelize. JSON:API v1.0 recommended using a dash (e.g."favorite-color": blue). If your API uses dashed fields, set this value to:dasherize. If your API uses underscores (e.g."favorite_color": "red")set to:underscore. To transform only the top-level field keys, use:camelize_shallow or:dasherize_shallow.
• remove_links.links data can optionally be removed from the payload viasetting the configuration above totrue. Defaults tofalse.
• json_library. Defaults toJason.
• paginator. Module implementing pagination links generation. Defaults tonil.

Pagination links can be generated by overriding theJSONAPI.View.pagination_links/4 callback of your view and returning a map containing the links.

...defpagination_links(data,conn,page,options)do%{first:nil,last:nil,prev:nil,next:nil}end...

Alternatively you can define generic pagination strategies by implementing a moduleconforming to theJSONAPI.Paginator behavior

defmodulePageBasedPaginatordo@moduledoc"""  Page based pagination strategy  """@behaviourJSONAPI.Paginator@impltruedefpaginate(data,view,conn,page,options)donumber=page|>Map.get("page","0")|>String.to_integer()size=page|>Map.get("size","0")|>String.to_integer()total_pages=Keyword.get(options,:total_pages,0)%{first:view.url_for_pagination(data,conn,Map.put(page,"page","1")),last:view.url_for_pagination(data,conn,Map.put(page,"page",total_pages)),next:next_link(data,view,conn,number,size,total_pages),prev:previous_link(data,view,conn,number,size)}enddefpnext_link(data,view,conn,page,size,total_pages)whenpage<total_pages,do:view.url_for_pagination(data,conn,%{size:size,page:page+1})defpnext_link(_data,_view,_conn,_page,_size,_total_pages),do:nildefpprevious_link(data,view,conn,page,size)whenpage>1,do:view.url_for_pagination(data,conn,%{size:size,page:page-1})defpprevious_link(_data,_view,_conn,_page,_size),do:nilend

and configuring it as the global pagination logic in yourmix.config

config:jsonapi,:paginator,PageBasedPaginator

or as the view pagination logic when usingJSONAPI.View

useJSONAPI.View,paginator:PageBasedPaginator

Links can be generated using theJSONAPI.Config.page information stored in the connection assignjsonapi_query and by passing additional information to thepagination_links/4 callback or your paginator module by passingoptions from your controller.

Actual pagination is expected to be handled in your application logic and is outside the scope of this library.

• Feel free to make PR's. I will do my best to respond within a day or two.
• If you want to take one of the TODO items just create an issue or PR and let me know so we avoid duplication.
• If you need help, I am on irc and twitter.
• Example project