Granola, a JSON serializer

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 Yajl:

Granola.json = Yajl::Encoder.method(:encode)

If your project already uses MultiJson then we will default to whatever it's using, so you shouldn't worry. Be warned that using MultiJson instead of using a library (such as Yajl) straight away incurs a small performance penalty (see, and run, the benchmark).

Handling lists of models

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 simply include Granola::Rack and you 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):

Cuba.plugin Granola::Rack

Cuba.define do
  on get, "users/:id" do |id|
    user = User[id]
    halt granola(user)
  end
end

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.

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"

class BaseSerializer < Granola::Serializer
  MIME_TYPES[:msgpack] = "application/x-msgpack".freeze

  def to_msgpack(*)
    MsgPack.pack(data)
  end
end

Now all serializers that inherit from BaseSerializer can be data into MsgPack. In order to use this from our Rack helpers, you'd do:

granola(object, as: :msgpack)

This will set the correct MIME type.

License

This project is shared under the MIT license. See the attached LICENSE file for details.