foca / granola

Simple JSON serializers (Cereal-izers. GET IT?)

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 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.

granola's Issues

Default rendering format to `env["HTTP_ACCEPT"]` in Rack helper

When calling the rack helper, if a user doesn't pass an explicit value for as: we should search through the registered renderers for one whose content_type matches the request's Accept header.

Caching

It would be nice to have some mechanism for caching the generated JSON responses, instead of only providing ETag / Last-Modified support.

Probably a good candidate for a plugin, as it's somewhat orthogonal to the serialization itself.

Published gem is missing granola/serializer.rb

$ ruby -v
ruby 2.2.1p85 (2015-02-26 revision 49769) [x86_64-darwin14]

$ gem -v
2.4.5

$ gem fetch granola
Fetching: granola-0.10.0.gem (100%)
Downloaded granola-0.10.0

$ gem spec granola-0.10.0.gem files

---
- LICENSE
- README.md
- lib/granola.rb
- lib/granola/caching.rb
- lib/granola/rack.rb
- lib/granola/version.rb

Attempt to require the gem result in error:

$ ruby -rgranola -e "puts :ok"
/usr/local/rubies/ruby-2.2.1/lib/ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- granola/serializer (LoadError)

Seems the file is missing form the gemspec definition.

Thank you!

Drop MultiJson support

If your app relies on MultiJson, it's pretty easy to plug in with the new API for defining renderers.

However, if your app does not rely on MultiJson, but indirectly requires it at some point by depending on one of the many (roughly ~2000 at the time of writing), we will switch to using it instead of the JSON library.

This incurs a heavy performance penalty. The best solution IMO is drop the automatic switching, and allowing people to explicitly set they desire to render via MultiJson where appropriate.

Remove reliance on MultiJson

In the past I've had gem conflicts because of MultiJson, and, in my opinion, it's not worth to have a dependency on something that is merely a strategy definition.

So instead of depending on it and calling MultiJson.dump (or whatever its API is), you could use something like:

Granola.json = {
  parse: -> str { JSON.parse(str) },
  dump: -> o { o.to_json }
}

What do you think?

Allow for automatic discovery of namespaced serializers

Right now Utils.serializer_class_for will only discover serializer classes that are defined at the top-level namespace.

It would be nice to have a hook to allow users to define their own constant lookup, so that users that have serializers defined in namespaces (e.g. API::V2::UserSerializer) can use the auto discovery.

Something along the lines of:

Granola::Util.constant_lookup #=> Object.method(:const_get)
Granola::Util.constant_lookup = API::V2.method(:const_get)

Should be enough.

Rails support

Similar as to how we have a rack helper, it would be nice to have hooks into Rails' rendering so we could do something along the lines of

  render json: something, with: SomeSerializer