granola-schema 0.0.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 02cf64484c5f354c2a89a84f30e1ca45a304c8c0
-  data.tar.gz: fa604062d1279a33bad7eb7eb70844e0a2311754
+  metadata.gz: 361ab0951c367d4e574849c14618f3706d0b3ee7
+  data.tar.gz: 6c925857257d586bcd8abaf6a83ac147cb7711cf
 SHA512:
-  metadata.gz: 1adb7a313efb88297ff27fb377479c17c91b02d9c11c2dff31635ce6ed92cbb66fd8693ec54c2a09da0f3743160ad49fbb8220c858d2d3772da244ebd295ac6a
-  data.tar.gz: 344ab9d3184b53f732eb3d6b5b9f40ef6b7441019b354c6748bc17f64b31f663b2864663775921544e3dc876c6e08649927405190ffbb19c9ffff31c7666a75a
+  metadata.gz: 45260d91c3143723a6a52063a1ba3bde5360eac45740951675943a5aaae695637a918f0152ef56fbf67e3c658c0ed963218b6cba3d1882819bc5c24703a51f71
+  data.tar.gz: a38320a37f9f50c9dfb13c386279ed58febf997d5124a13773de94ec782a6c269405b098ecafb42b88736897db5ee3fafbd1d6d585a3aa7f153262b2ddb48207

data/README.md

@@ -1,4 +1,4 @@
-# Granola, a JSON serializer
+# Granola, a JSON serializer [![Build Status](https://travis-ci.org/foca/granola.svg?branch=master)](https://travis-ci.org/foca/granola)
 
 ![A tasty bowl of Granola](https://cloud.githubusercontent.com/assets/437/4827156/9e8d33da-5f76-11e4-8574-7803e84845f2.JPG)
 
@@ -11,7 +11,7 @@ gets out of your way. You just write plain ruby.
 
 ``` ruby
 class PersonSerializer < Granola::Serializer
-  def attributes
+  def serialized
     {
       "name" => object.name,
       "email" => object.email,
@@ -34,10 +34,14 @@ specific JSON backend. It defaults to the native JSON backend, but you're free
 to change it. For example, if you were using [Yajl][]:
 
 ``` ruby
-Granola.json = ->(obj, **opts) { Yajl::Encoder.encode(obj, opts) }
+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.
+
 [Yajl]: https://github.com/brianmario/yajl-ruby
+[MultiJson]: https://github.com/intridea/multi_json
 
 ## Handling lists of models
 
@@ -55,8 +59,8 @@ If your application is based on Rack, you can simply `include Granola::Rack` and
 you get access to the following interface:
 
 ``` ruby
-json(person) #=> This will try to infer PersonSerializer from a Person instance
-json(person, with: AnotherSerializer)
+granola(person) #=> This will infer PersonSerializer from a Person instance
+granola(person, with: AnotherSerializer)
 ```
 
 *NOTE* The method relies on being an `env` method that returns the Rack
@@ -72,7 +76,7 @@ Cuba.plugin Granola::Rack
 Cuba.define do
   on get, "users/:id" do |id|
     user = User[id]
-    halt json(user)
+    halt granola(user)
   end
 end
 ```
@@ -81,16 +85,77 @@ end
 
 ## Caching
 
-`Granola::Serializer` gives you to methods that you can implement in your
-serializers, `last_modified` and `cache_key`, that will be used to prevent
-rendering JSON at all if possible, when using the `Granola::Rack#json` helper.
+`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`][cg]
+middleware is in your Rack stack, as it will use these headers to avoid
+generating the JSON response altogether. For example, using Cuba:
+
+``` ruby
+class UserSerializer < Granola::Serializer
+  def serialized
+    { "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.
+
+[cg]: http://www.rubydoc.info/github/rack/rack/Rack/ConditionalGet
+
+## 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:
+
+``` ruby
+require "msgpack"
+
+class BaseSerializer < Granola::Serializer
+  MIME_TYPES[:msgpack] = "application/x-msgpack".freeze
+
+  def to_msgpack(*)
+    MsgPack.pack(serialized)
+  end
+end
+```
+
+Now all serializers that inherit from `BaseSerializer` can be serialized into
+MsgPack. In order to use this from our Rack helpers, you'd do:
+
+``` ruby
+granola(object, as: :msgpack)
+```
 
-If your serializer implements this method, and the `env` has the appropriate
-`If-Modified-Since` or `If-None-Match` headers, the helper will automatically
-return a 304 response.
+This will set the correct MIME type.
 
-Plus, it sets appropriate `ETag` and `Last-Modified` so your clients can avoid
-hitting the endpoint altogether.
+[msgpack-ruby]: https://github.com/msgpack/msgpack-ruby
 
 ## License
 

data/lib/granola/schema.rb

@@ -26,7 +26,7 @@ module Granola
       def valid?
         validation_errors.clear
         validation_errors.concat(
-          JSON::Validator.fully_validate(self.class.schema, attributes)
+          JSON::Validator.fully_validate(self.class.schema, serialized)
         )
         validation_errors.empty?
       end
@@ -52,7 +52,7 @@ module Granola
   #   serializer = SchemaSerializer.new(PersonSerializer.schema)
   #   serializer.to_json
   class SchemaSerializer < Serializer
-    def attributes
+    def serialized
       {
         "$schema".freeze => "http://json-schema.org/schema#".freeze,
         "type".freeze => "object".freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: granola-schema
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.9.0
 platform: ruby
 authors:
 - Nicolas Sanguinetti
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-23 00:00:00.000000000 Z
+date: 2015-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: granola
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.4
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.4
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement