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.
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
- Declaration syntax similar to Active Model Serializer
- Support for
belongs_to,has_manyandhas_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
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
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": "232",
"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"
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 |
| 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 |
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
We're Hiring!
Join the Netflix Studio Engineering team and help us build gems like this!