It's been a long time coming, but the JSON API spec is nearing a 1.0 release. Dan and I have been actively involved in helping to form this spec, which appeals to us because it is so ambitious and comprehensive. JSON API goes beyond specifying a format for JSON payloads - it also specifies how data should be fetched and modified. By standardizing so many of the decisions around designing and building an API, JSON API allows developers to focus on the design of their applications. As JSON API catches on, we'll all benefit from the standardized tooling that develops for both clients and servers.

Our initial contribution to this tooling is JSONAPI::Resources, or "JR". JR is a gem that allows Rails apps to easily support the JSON API spec. As you may have guessed from the name, JR is resource-centric. You define resources for your application and JR can automatically fulfill requests to fetch and modify them. JR not only handles the serialization of responses, but also provides controllers that support methods to interact with the resource. By declaring resource relationships you can allow related resources to be retrieved in compound documents, and by specifying resource attributes you can control how the resource is represented to the API client.

Until now, we've been using (and recommending and contributing toward) ActiveModel::Serializers, or "AMS", the Ruby library that has come closest to fulfilling the JSON API spec. There are a couple reasons that we developed JR instead of continuing to work with AMS. First of all, AMS is not strictly focused on JSON API, and has been out of compliance for some time. This is not a major hurdle and could be easily overcome by enabling a JSON API mode in AMS, something which is already under discussion. The primary reason we developed JR is that AMS is focused on serializers and not resources. While serializers are just concerned with the representation of a model, resources can also act as a proxy to a backing model. In this way, JR can assist with fetching and modifying resources, and can therefore handle all aspects of JSON API.

Components

Let's take a quick look at the major components of JSONAPI::Resources.

Resource

You can define the resources available through your API as subclasses of JSONAPI::Resource. A resource definition looks very similar to the definition of a serializer in AMS. Resources form the core of JR and are used by many of its components.

Let's say we're building a blog. Here's a simple resource definition for posts:

1
2
3
4
5
6
7
require 'json/api/resource'

class PostResource < JSONAPI::Resource
  attributes :id, :title, :body

  has_one :author
end

And here's a corresponding author:

1
2
3
4
5
class AuthorResource < JSONAPI::Resource
  attributes :id, :name

  has_many :posts
end

All declared attributes can, by default, be accessed through the API. There are also methods on a resource that you can implement to control which of the attributes are creatable, updateable, and fetchable. Any attribute on the underlying object that isn't declared in the resource definition will not be available through the resource.

Relationships support options to set different class names and keys from the resource names. In addition, a relationship can be treated "as a set" for create and update purposes.

In the following example, tags are defined with the acts_as_set option. This allows a collection of tags to be set on a post that will replace all of its existing tags:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class PostResource < JSONAPI::Resource
  attribute :id
  attribute :title
  attribute :body
  attribute :subject

  has_one :author, class_name: 'Person'
  has_one :section
  has_many :tags, acts_as_set: true
  has_many :comments

  def subject
    @object.title
  end

  def self.updateable(keys, context)
    super(keys - [:author, :subject])
  end

  def self.createable(keys, context)
    super(keys - [:subject])
  end

  filters :title, :author
  filter :id
end

Also note that the above resource has a computed attribute called subject. This is simply the title of the post, and is not createable or updateable.

A resource also controls which filters its corresponding ResourceController will support. The Resource class provides basic search capabilities, but if you need more control you can implement a find method on your resource.

ResourceSerializer

A ResourceSerializer can serialize a resource into a JSON API compliant hash, which can then be converted to JSON. ResourceSerializer has a serialize method that takes a resource instance to serialize, and optional fields, includes, and context parameters.

For example:

1
2
post = Post.find(1)
JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post))

This returns a hash like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  posts: [{
    id: 1,
    title: 'New post',
    body: 'A body!!!',
    links: {
      section: nil,
      author: 1,
      tags: [1,2,3],
      comments: [1,2]
    }
  }]
}

You can also provide some options and filter the fields and include related records. include takes an array of related resources to serialize, and fields takes a hash of resource types to an array of attributes. For example:

1
2
3
4
5
6
7
post = Post.find(1)
JSONAPI::ResourceSerializer.new.serialize(PostResource.new(post),
  ['comments','author','comments.tags','author.posts'],
  {people: [:id, :email, :comments],
   posts: [:id, :title, :author],
   tags: [:name],
   comments: [:id, :body, :post]})

This outputs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  :posts=>[
    {:id=>1,
     :title=>"New post",
     :links=>{:author=>1}}
    ],
    :linked=>{
      :posts=>[
        {:id=>2, :title=>"JR solves your serialization woes!", :links=>{:author=>1}}
      ],
      :people=>[
        {:id=>1, :email=>"joe@xyz.fake", :links=>{:comments=>[1]}}
      ],
      :tags=>[
        {:name=>"whiny"}, {:name=>"short"}, {:name=>"happy"}
      ],
      :comments=>[
        {:id=>1, :body=>"what a dumb post", :links=>{:post=>1}},
        {:id=>2, :body=>"i liked it", :links=>{:post=>1}}
      ]
    }
}

Note that multilevel includes can be specified with a dot notation, like 'author.posts'. In addition, you can control the fields for each resource type.

ResourceController

The ResourceController class provides index, show, create, update, delete, show_association, create_association, and destroy_association methods that function based on the resource definition matching the controller name. The easiest way to use ResourceController is to derive your ApplicationController from it, and in turn derive specific controllers from your ApplicationController. There is no need for any methods to exist in your individual controllers unless you need to alter the default behavior.

1
2
3
4
5
class ApplicationController < JSONAPI::ResourceController
end

class ContactsController < ApplicationController
end

The ResourceController translates the includes and fields parameters from the JSON API specified style into the internal structures used by the ResourceSerializer.

For example, the following request will get all the contacts with their included phone numbers:

1
http://localhost:3000/contacts?include=phone_numbers&fields[contacts]=name_first,name_last&fields[phone_numbers]=number

The contact records will only contain the first and last names and the phone number will just contain the number.

Of course, you don't need to use ResourceController if your needs are different.

Routing

JR has a couple of helper methods available to assist you with setting up routes.

jsonapi_resources

Like resources in ActionDispatch, jsonapi_resources provides resourceful routes mapping between HTTP verbs and URLs and controller actions. This will also setup mappings for relationship URLs for a resource's associations. For example:

1
2
3
4
5
6
require 'jsonapi/routing_ext'

Peeps::Application.routes.draw do
  jsonapi_resources :contacts
  jsonapi_resources :phone_numbers
end

This generates the following routes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
                     Prefix Verb   URI Pattern                                               Controller#Action
contact_links_phone_numbers GET    /contacts/:contact_id/links/phone_numbers(.:format)       contacts#show_association {:association=>"phone_numbers"}
                            POST   /contacts/:contact_id/links/phone_numbers(.:format)       contacts#create_association {:association=>"phone_numbers"}
                            DELETE /contacts/:contact_id/links/phone_numbers/:keys(.:format) contacts#destroy_association {:association=>"phone_numbers"}
                   contacts GET    /contacts(.:format)                                       contacts#index
                            POST   /contacts(.:format)                                       contacts#create
                new_contact GET    /contacts/new(.:format)                                   contacts#new
               edit_contact GET    /contacts/:id/edit(.:format)                              contacts#edit
                    contact GET    /contacts/:id(.:format)                                   contacts#show
                            PATCH  /contacts/:id(.:format)                                   contacts#update
                            PUT    /contacts/:id(.:format)                                   contacts#update
                            DELETE /contacts/:id(.:format)                                   contacts#destroy
 phone_number_links_contact GET    /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#show_association {:association=>"contact"}
                            POST   /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#create_association {:association=>"contact"}
                            DELETE /phone_numbers/:phone_number_id/links/contact(.:format)   phone_numbers#destroy_association {:association=>"contact"}
              phone_numbers GET    /phone_numbers(.:format)                                  phone_numbers#index
                            POST   /phone_numbers(.:format)                                  phone_numbers#create
           new_phone_number GET    /phone_numbers/new(.:format)                              phone_numbers#new
          edit_phone_number GET    /phone_numbers/:id/edit(.:format)                         phone_numbers#edit
               phone_number GET    /phone_numbers/:id(.:format)                              phone_numbers#show
                            PATCH  /phone_numbers/:id(.:format)                              phone_numbers#update
                            PUT    /phone_numbers/:id(.:format)                              phone_numbers#update
                            DELETE /phone_numbers/:id(.:format)                              phone_numbers#destroy

Use jsonapi_resource for singleton resources that can be looked up without an id.

You can control the relationship routes by passing a block into jsonapi_resources or jsonapi_resource. An empty block will not create any relationship routes.

You can add individual relationship routes with jsonapi_links. For example:

1
2
3
4
      jsonapi_resources :posts, except: [:destroy] do
        jsonapi_link :author, except: [:destroy]
        jsonapi_links :tags, only: [:show, :create]
      end

This will create relationship routes for author (show and create, but not destroy) and for tags (again show and create, but not destroy).

Getting started

We've shared a simple contact manager app created with JR called Peeps, which you can pull down and play with (some curl examples are provided). It also contains instructions for how to recreate the app if you want to see just what's involved. Hint - it's not much.

Status and Next Steps

So is JSONAPI::Resources complete? In a word, no. It is functional, but it is missing plenty of features. The biggest, as far as I see them, are pagination, sorting, and support for PATCH operations. Also not yet implemented are the top level meta and links objects. I plan to add these over time and would love community support to make and keep JR as compliant with JSON API as possible.

In very basic testing I have found JSONAPI::Resources to be anywhere from 20% to 50% faster than the equivalent operation using version 0.8.1 of ActiveModel Serializers and 5% to 20% faster than the 0.9.0alpha master branch. Of course, there's probably some speed that can still be extracted from both projects.

I hope you find JSONAPI::Resources useful for building your own APIs. I'd appreciate your comments as well as your contributions.