- An extremely simple JSON Api serializer.
- It supports serializing any Ruby object.
- It does not target a specific framework.
Add this line to your application's Gemfile:
gem 'simple-json-api-serializer'
And then execute:
$ bundle
Or install it yourself as:
$ gem install simple-json-api-serializer
You can use the JSONApi::Serializer in two ways:
- In a DSL like manner by declaring your configuration in as subclass of
JSONApi::ObjectSerializerDefinition
- By using
JSONApi::Serializer#to_json
directly with an object and a configuration hash
The simplest serializer you can declare looks like this:
class MyObjectSerializer < JSONApi::ObjectSerializerDefinition
end
You can then serialize objects with it:
MyObject = Struct.new(:id)
my_object = MyObject.new(1)
MyObjectSerializer.serialize(my_object)
Which generates:
{
"data": {
"type": "my-objects",
"id": "1"
}
}
You can also use the hashify
function:
MyObjectSerializer.hashify(my_object)
# { :data => { :type => "my-objects", :id => "1" } }
class PersonSerializer < JSONApi::ObjectSerializerDefinition
id_attribute :ssn
attributes :first_name, :last_name
end
Person = Struct.new(:ssn, :first_name, :last_name)
joe = Person.new('X3DAB4CFJ0', 'Joe', 'Strummer')
PersonSerializer.serialize(joe)
Generates:
{
"data": {
"type": "persons",
"id": "X3DAB4CFJ0",
"attributes": {
"first-name": "Joe",
"last-name": "Strummer"
}
}
}
class PostSerializer < JSONApi::ObjectSerializerDefinition
attributes :title, :content
has_one :author
has_many :comments
end
Post = Struct.new(:id, :title, :content, :author, :comments) do
def author_id
author.id
end
def comment_ids
comments.map(&:id)
end
end
post = Post.new(1, "How to serialize objects", "...", author, comments)
PostSerializer.serialize(post)
Generates:
{
"data": {
"type": "posts",
"id": "1",
"attributes": {
"title": "How to serialize objects",
"content": "...",
},
"relationships": {
"author": {
"data": { "type": "authors", "id": "42" },
},
"comments": {
"links": {
"related": "/posts/1/comments"
}
}
}
}
}
If your object does not abide by the _id
or _ids
convention for relations,
you can specify what method should be called to retrieve the foreign key with
has_one :author, foreign_key: :username
You can also specify the type of the related object with:
has_one :author, type: :user
.
By default has_one
relationships will include a data
object but not links
and has_many
relationships will include a links
object but not data
. This
can be customized by setting the links
and data
options to true
or
false
.
You can add includes by adding passing an array of objects to the serialize function:
comments_json_hash = CommentSerializer.hashify(comments)
PostSerializer.serialize(post, include: comments_json_hash)
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/martndemus/simple-json-api-serializer. 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.