CollectionJson

An experimental gem to help with producing Hypermedia APIs with a MIME type of 'application/vnd.collection+json'

see http://amundsen.com/media-types/collection/format/

Usage

The aim is to include the gem in a Rack app to generate hypermedia APIs from your resources, effectively a hypermedia decorator.

Here's a preview of what you should be able to do in a Rails app:

Spider cow

class SpiderCowController < ApplicationController
  respond_to :collection_json

  def index
    @spider_cows = SpiderCowDecorator.all do |collection, item|
      collection.href "http://www.youtube.com/watch?v=FavUpD_IjVY"

      item.links [{href: spider_cow_path(item),        rel: "self"},
                  {href: spider_cow_path(item.father), rel: "father"}]
    end

    respond_with @spider_cows
  end
end

class SpiderCow < ActiveRecord::Base
  #attributes - legs, eyes, udders
end

class SpiderCowDecorator
  extend CollectionJson::Decorator
end

Sample output:

{"collection" :
  {
    "version" :"1.0",
    "href" :"http://example.org/spider_cows/",

    "links" :[ {"rel" :"father", "href" :"http://example.com/spider_cows/tom"}],

    "items" :
    [
      {"data" :
       [{"name" :"legs", "value" :7},
        {"name" :"eyes", "value" :8},
        {"name" :"udders", "value" :"blue"}
       ]
      },

      {"data" :
       [{"name" :"legs",  "value" :6},
        {"name" :"udders", "value" :"red"}
       ]
      }
    ]
  }
}

Installation

Add this line to your application's Gemfile:

gem 'collection_json'

And then execute:

$ bundle

Or install it yourself as:

$ gem install collection_json

Notes

Collection+JSON specifies the following concepts

Create, Read, Update, Delete, Template and Query which correspond to the ideas in Rails like so:

VerbRailsCollection+JSON
POST create create
GET show read
PUT update update
DELETEdestroy delete
GET edit/newtemplate
GET index query

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request