When serializing with fast_jsonapi, data is structured per the json-api specs.
lp-serializable is a thin wrapper around fast_jsonapi serialization, producting AMS style output.
lp-serializable is intended to be used in Rails controllers.
Add this line to your application's Gemfile:
gem 'lp-serializable'
And then execute:
$ bundle
Or install it yourself as:
$ gem install lp-serializable
Controller Definition
class ApplicationController < ActionController::Base
include Lp::Serializable
end
class MoviesController < ApplicationController
def index
movies = Movie.all
movies_hash = serializable_collection(movies, 'Movie')
render json: movies_hash
end
def show
movie = Movie.find(params[:id])
movie_hash = serializable(movie)
render json: movie_hash
end
end
Serializer Definition
class MovieSerializer
include FastJsonapi::ObjectSerializer
attributes :name
attribute :year, if: Proc.new { |object| object.year.present? }
attribute :last_updated do |object|
object.updated_at
end
has_many :actors
belongs_to :owner
end
class ActorSerializer
include FastJsonapi::ObjectSerializer
attributes :id
end
class OwnerSerializer
include FastJsonapi::ObjectSerializer
attributes :id
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
Return a hash
hash = serializable(movie)
Output
{
"data": {
"id": "3",
"type": "movie",
"name": "test movie",
"last_updated": "2019-04-26 18:55:46 UTC",
"actors": [
{
"id": "1",
"type": "actor"
},
{
"id": "2",
"type": "actor"
}
],
"owner": {
"id": "3",
"type": "user"
}
}
}
For more information on configuration, refer to fast_jsonapi documentation.
Fastjson API does not support serialization of deeply nested resources.
To get around this, extend Lp::Serializable
in your serializers:
class MovieSerializer
include FastJsonapi::ObjectSerializer
extend Lp::Serializable
...
end
Define custom attributes for relationships, instead of defining them via fastjson_api:
class MovieSerializer
include FastJsonapi::ObjectSerializer
extend Lp::Serializable
attribute :actors do |object|
collection = object.actors
serializer = 'Actor'
serializable_collection(collection, serializer, nested: true)
end
end
Attribute :actors
will trigger ActorSerializer
to serialize the actors collection. Consequently, any relationships defined in ActorSerializer
via custom attributes and serialized with serializable_
methods (using the nested: true
option) will be appropriately nested.
Use #serializable_class
to serialize with a custom class:
def show
movie = Movie.find(params[:id])
# Will serialize with FilmSerializer instead of MovieSerializer
movie_hash = serializable_class(movie, 'Film')
render json: movie_hash
end
Supported options include:
:fields
(Sparse Fieldsets):params
(Params)- Conditional Attributes
Other options are "supported" but may yeild unexpected results, as Serializable's hash flattening prioritizes deeply nested data structures.
:is_collection
is baked into Seriazable methods for accurate detection of collections or singular resources.
serialize_and_flatten()
=serializable()
serialize_and_flatten_with_class_name()
=serializable_class()
serialize_and_flatten_collection()
=serializable_collection()
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/LaunchPadLab/lp-serializable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Lp::Serializable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.