Fast JSON API

A lightning fast JSON:API serializer for Ruby Objects.

Performance Comparison

We compare serialization times with Active Model Serializer as part of RSpec performance tests included on this library. We want to ensure that with every change on this library, serialization time is at least 25 times faster than Active Model Serializers on up to current benchmark of 1000 records. Please read the performance document for any questions related to methodology.

Benchmark times for 250 records

$ rspec
Active Model Serializer serialized 250 records in 138.71 ms
Fast JSON API serialized 250 records in 3.01 ms

Table of Contents

• Features
• Installation
• Usage
  • Rails Generator
  • Model Definition
  • Serializer Definition
  • Object Serialization
  • Compound Document
  • Key Transforms
  • Collection Serialization
  • Caching
• Contributing

Features

• Declaration syntax similar to Active Model Serializer
• Support for belongs_to, has_many and has_one
• Support for compound documents (included)
• Optimized serialization of compound documents
• Caching

Installation

Add this line to your application's Gemfile:

gem 'fast_jsonapi'

Execute:

$ bundle install

Usage

Rails Generator

You can use the bundled generator if you are using the library inside of a Rails project:

rails g Serializer Movie name year

This will create a new serializer in app/serializers/movie_serializer.rb

Model Definition

class Movie
  attr_accessor :id, :name, :year, :actor_ids, :owner_id, :movie_type_id
end

Serializer Definition

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  set_type :movie  # optional
  set_id :owner_id # optional
  attributes :name, :year
  has_many :actors
  belongs_to :owner, record_type: :user
  belongs_to :movie_type
end

Sample Object

movie = Movie.new
movie.id = 232
movie.name = 'test movie'
movie.actor_ids = [1, 2, 3]
movie.owner_id = 3
movie.movie_type_id = 1
movie

Object Serialization

Return a hash

hash = MovieSerializer.new(movie).serializable_hash

Return Serialized JSON

json_string = MovieSerializer.new(movie).serialized_json

Serialized Output

{
  "data": {
    "id": "3",
    "type": "movie",
    "attributes": {
      "name": "test movie",
      "year": null
    },
    "relationships": {
      "actors": {
        "data": [
          {
            "id": "1",
            "type": "actor"
          },
          {
            "id": "2",
            "type": "actor"
          }
        ]
      },
      "owner": {
        "data": {
          "id": "3",
          "type": "user"
        }
      }
    }
  }
}

Key Transforms

By default fast_jsonapi underscores the key names. It supports the same key transforms that are supported by AMS. Here is the syntax of specifying a key transform

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  # Available options :camel, :camel_lower, :dash, :underscore(default)
  set_key_transform :camel
end

Here are examples of how these options transform the keys

set_key_transform :camel # "some_key" => "SomeKey"
set_key_transform :camel_lower # "some_key" => "someKey"
set_key_transform :dash # "some_key" => "some-key"
set_key_transform :underscore # "some_key" => "some_key"

Attributes

Attributes are defined in FastJsonapi using the attributes method. This method is also aliased as attribute, which is useful when defining a single attribute.

By default, attributes are read directly from the model property of the same name. In this example, name is expected to be a property of the object being serialized:

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  
  attribute :name
end

Custom attributes that must be serialized but do not exist on the model can be declared using Ruby block syntax:

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  
  attributes :name, :year
  
  attribute :name_with_year do |object|
    "#{object.name} (#{object.year})"
  end
end

The block syntax can also be used to override the property on the object:

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  
  attribute :name do |object|
    "#{object.name} Part 2"
  end
end

Compound Document

Support for top-level included member through options[:include].

options = {}
options[:meta] = { total: 2 }
options[:include] = [:actors]
MovieSerializer.new([movie, movie], options).serialized_json

Collection Serialization

options[:meta] = { total: 2 }
hash = MovieSerializer.new([movie, movie], options).serializable_hash
json_string = MovieSerializer.new([movie, movie], options).serialized_json

Caching

class MovieSerializer
  include FastJsonapi::ObjectSerializer
  set_type :movie  # optional
  cache_options enabled: true, cache_length: 12.hours
  attributes :name, :year
end

Customizable Options

Option	Purpose	Example
set_type	Type name of Object	set_type :movie
set_id	ID of Object	set_id :owner_id
cache_options	Hash to enable caching and set cache length	cache_options enabled: true, cache_length: 12.hours
id_method_name	Set custom method name to get ID of an object	has_many :locations, id_method_name: :place_ids
object_method_name	Set custom method name to get related objects	has_many :locations, object_method_name: :places
record_type	Set custom Object Type for a relationship	belongs_to :owner, record_type: :user
serializer	Set custom Serializer for a relationship	has_many :actors, serializer: :custom_actor

Instrumentation

fast_jsonapi also has builtin Skylight integration. To enable, add the following to an initializer:

require 'fast_jsonapi/instrumentation/skylight'

Skylight relies on ActiveSupport::Notifications to track these two core methods. If you would like to use these notifications without using Skylight, simply require the instrumentation integration:

require 'fast_jsonapi/instrumentation'

The two instrumented notifcations are supplied by these two constants:

• FastJsonapi::ObjectSerializer::SERIALIZABLE_HASH_NOTIFICATION
• FastJsonapi::ObjectSerializer::SERIALIZED_JSON_NOTIFICATION

It is also possible to instrument one method without the other by using one of the following require statements:

require 'fast_jsonapi/instrumentation/serializable_hash'
require 'fast_jsonapi/instrumentation/serialized_json'

Same goes for the Skylight integration:

require 'fast_jsonapi/instrumentation/skylight/normalizers/serializable_hash'
require 'fast_jsonapi/instrumentation/skylight/normalizers/serialized_json'

Contributing

Please see contribution check for more details on contributing

Running Tests

We use RSpec for testing. We have unit tests, functional tests and performance tests. To run tests use the following command:

rspec

To run tests without the performance tests (for quicker test runs):

rspec spec --tag ~performance:true

To run tests only performance tests:

rspec spec --tag performance:true

We're Hiring!

Join the Netflix Studio Engineering team and help us build gems like this!

• Senior Ruby Engineer
• Senior Platform Engineer