A lightning fast JSON:API serializer for Ruby Objects.
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.
$ rspec
Active Model Serializer serialized 250 records in 138.71 ms
Fast JSON API serialized 250 records in 3.01 ms
- Declaration syntax similar to Active Model Serializer
- Support for
belongs_to
,has_many
andhas_one
- Support for compound documents (included)
- Optimized serialization of compound documents
- Caching
Add this line to your application's Gemfile:
gem 'fast_jsonapi'
Execute:
$ bundle install
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
class Movie
attr_accessor :id, :name, :year, :actor_ids, :owner_id, :movie_type_id
end
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
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
hash = MovieSerializer.new(movie).serializable_hash
json_string = MovieSerializer.new(movie).serialized_json
{
"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"
}
}
}
}
}
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 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
Support for top-level included member through options[:include]
.
options = {}
options[:meta] = { total: 2 }
options[:include] = [:actors]
MovieSerializer.new([movie, movie], options).serialized_json
options[:meta] = { total: 2 }
hash = MovieSerializer.new([movie, movie], options).serializable_hash
json_string = MovieSerializer.new([movie, movie], options).serialized_json
class MovieSerializer
include FastJsonapi::ObjectSerializer
set_type :movie # optional
cache_options enabled: true, cache_length: 12.hours
attributes :name, :year
end
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 |
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'
Please see contribution check for more details on contributing
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
Join the Netflix Studio Engineering team and help us build gems like this!