restpack_serializer

restpack_serializer

Model serialization, paging, side-loading and filtering

restpack_serializer allows you to quickly provide a set of RESTful endpoints for your application. It is an implementation of the emerging JSON API standard.

Live Demo of RestPack Serializer

NOTE: This gem needs maintainers: https://github.com/RestPack/restpack_serializer/issues/128

• An overview of RestPack
• JSON API

Getting Started

For rails projects:

After adding the gem restpack_serializer to your Gemfile, add this code to config/initializers/restpack_serializer.rb:

Dir[Rails.root.join('app/serializers/**/*.rb')].each do |path|
  require path
end

Serialization

Let's say we have an Album model:

class Album < ActiveRecord::Base
  attr_accessible :title, :year, :artist

  belongs_to :artist
  has_many :songs
end

restpack_serializer allows us to define a corresponding serializer:

class AlbumSerializer
  include RestPack::Serializer
  attributes :id, :title, :year, :artist_id, :href
end

AlbumSerializer.as_json(album) produces:

{
  "id": "1",
  "title": "Kid A",
  "year": 2000,
  "artist_id": 1,
  "href": "/albums/1"
}

as_json accepts an optional context hash parameter which can be used by your Serializers to customize their output:

class AlbumSerializer
  include RestPack::Serializer
  attributes :id, :title, :year, :artist_id, :extras
  optional :score

  can_include :artists, :songs
  can_filter_by :year

  def extras
    if @context[:admin?]
      { markup_percent: 95 }
    end
  end
end

AlbumSerializer.as_json(album, { admin?: true })

All attributes are serialized by default. If you'd like to skip an attribute, you can pass an option in the @context as follows:

AlbumSerializer.as_json(album, { include_title?: false })

You can also define optional attributes which aren't included by default. To include:

AlbumSerializer.as_json(album, { include_score?: true })

Exposing an API

The AlbumSerializer provides page and resource methods which provide paged collection and singular resource GET endpoints.

class AlbumsController < ApplicationController
  def index
    render json: AlbumSerializer.page(params)
  end

  def show
    render json: AlbumSerializer.resource(params)
  end
end

These endpoint will live at URLs such as /albums and /albums/142857:

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json
• http://restpack-serializer-sample.herokuapp.com/api/v1/albums/4.json

The AlbumSerializer also provides a single method which will return a serialized resource similar to as_json above.

page, resource and single methods take an optional scope argument allowing us to enforce arbitrary constraints:

AlbumSerializer.page(params, Albums.where("year < 1950"))

In addition to scope, all three methods also accept an optional context hash:

AlbumSerializer.page(params, Albums.where("year < 1950"), { admin?: true })

Other features:

• Custom Attributes Hash

Paging

Collections are paged by default. page and page_size parameters are available:

• http://restpack-serializer-sample.herokuapp.com/api/v1/songs.json?page=2
• http://restpack-serializer-sample.herokuapp.com/api/v1/songs.json?page=2&page_size=3

Paging details are included in a meta attribute:

http://restpack-serializer-sample.herokuapp.com/api/v1/songs.json?page=2&page_size=3 yields:

…

URL Templates to related data are included in the links element. These can be used to construct URLs such as:

• /artists/1
• /albums/1

Side-loading

Side-loading allows related resources to be optionally included in a single API response. Valid side-loads can be defined in Serializers by using can_include as follows:

class AlbumSerializer
  include RestPack::Serializer
  attributes :id, :title, :year, :artist_id, :href

  can_include :songs, :artists
end

In this example, we are allowing related songs and artists to be included in API responses. Side-loads can be specifed by using the include parameter:

No side-loads

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json

Side-load related Artists

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?include=artists

which yields:

…

Side-load related Songs

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?include=songs

An album :has_many songs, so the side-loaded songs are paged. The meta.songs includes previous_href and next_href which point to the previous and next page of this side-loaded data. These URLs take the form:

• http://restpack-serializer-sample.herokuapp.com/api/v1/songs.json?album_ids=1,2,3,4&page=2

Side-load related Artists and Songs

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?include=artists,songs

Filtering

Simple filtering based on primary and foreign keys is supported by default:

By primary key:

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?id=1
• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?ids=1,2,4

By foreign key:

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?artist_id=1
• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?artist_ids=2,3

Custom filters:

Custom filters can be defined with the can_filter_by option:

class Account
   include RestPack::Serializer
   attributes :id, :application_id, :created_by, :name, :href

   can_filter_by :application_id
end

Side-loading is available when filtering:

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?artist_ids=2,3&include=artists,songs

Sorting

Sorting attributes can be defined with the can_sort_by option:

class Account
   include RestPack::Serializer
   attributes :id, :application_id, :created_by, :name, :href

   can_sort_by :id, :name
end

• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?sort=id
• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?sort=-name
• http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json?sort=name,-id

Running Tests

bundle rake spec