Granola aims to provide a simple interface to generate JSON responses based on your application's domain models. It doesn't make assumptions about anything and gets out of your way. You just write plain ruby.
Example
class PersonSerializer < Granola::Serializer
def data
{
"name" => object.name,
"email" => object.email,
"age" => object.age
}
end
end
PersonSerializer.new(person).to_json #=> '{"name":"John Doe",...}'
Install
gem install granola
JSON serialization
Granola doesn't make assumptions about your code, so it shouldn't depend on a specific JSON backend. It defaults to the native JSON backend, but you're free to change it. For example, if you were using Oj:
Granola.render :json, via: Oj.method(:dump),
content_type: "application/json"
Handling lists of entities
A Granola serializer can handle a list of entities of the same type by using the
Serializer.list
method (instead of Serializer.new
). For example:
serializer = PersonSerializer.list(Person.all)
serializer.to_json #=> '[{"name":"John Doe",...},{...}]'
Rack Helpers
If your application is based on Rack, you can require "granola/rack"
instead
of require "granola"
, and then simply include Granola::Rack
to get access
to the following interface:
granola(person) #=> This will infer PersonSerializer from a Person instance
granola(person, with: AnotherSerializer)
This method returns a Rack response tuple that you can use like so (this example uses Cuba, but similar code will work for other frameworks):
require "granola/rack"
Cuba.plugin Granola::Rack
Cuba.define do
on get, "users/:id" do |id|
user = User[id]
halt granola(user)
end
end
Rails Support
The companion Granola::Rails gem takes care of support for Rails.
HTTP Caching
Granola::Serializer
gives you two methods that you can implement in your
serializers: last_modified
and cache_key
.
When using the Granola::Rack
module, you should return a Time
object from
your serializer's last_modified
. Granola will use this to generate the
appropriate Last-Modified
HTTP header. Likewise, the result of cache_key
will be MD5d and set as the response's ETag
header.
If you do this, you should also make sure that the Rack::ConditionalGet
middleware is in your Rack stack, as it will use these headers to avoid
generating the JSON response altogether. For example, using Cuba:
class UserSerializer < Granola::Serializer
def data
{ "id" => object.id, "name" => object.name, "email" => object.email }
end
def last_modified
object.updated_at
end
def cache_key
"user:#{object.id}:#{object.updated_at.to_i}"
end
end
Cuba.plugin Granola::Rack
Cuba.use Rack::ConditionalGet
Cuba.define do
on get, "users/:id" do |id|
halt granola(User[id])
end
end
This will avoid generating the JSON response altogether if the user sends the
appropriate If-Modified-Since
or If-None-Match
headers.
Caching of serialized bodies
If you are generating responses that are particularly expensive to serialize, you can use the Granola::Cache gem to store their representations once generated in an external cache.
Different Formats
Although Granola out of the box only ships with JSON serialization support, it's easy to extend and add support for different types of serialization in case your API needs to provide multiple formats. For example, in order to add MsgPack support (via the msgpack-ruby library), you'd do this:
require "msgpack"
Granola.render :msgpack, via: MessagePack.method(:pack),
content_type: "application/x-msgpack"
Now all serializers can be serialized into MsgPack using a to_msgpack
method.
In order to use this from our Rack helpers, you'd do:
granola(object, as: :msgpack)
This will set the correct MIME type.
If you don't explicitly set a format when rendering via the rack helper, Granola
will use the request's Accept
header to choose the best format for rendering.
For example, given a request with the following header:
Accept: text/x-yaml;q=0.5,application/x-msgpack;q=0.8,*/*;q=0.2
Granola will check first if you have a renderer registered for the
application/x-msgpack
MIME type, and then check for a renderer for the
text/x-yaml
MIME type. If none of these are registered, it will default to
rendering JSON.
License
This project is shared under the MIT license. See the attached LICENSE file for details.