Restful Serialization

A gem to help with serializing activerecord instances as Restful resources, including hrefs.

If the model has a name column, it will be used to describe the resource.

This library does not attempt to provide href info for transitions, or deal much with questions of authorization beyond what is specified in the serialization configuration lines. It assumes that these issues would be resolved in the controller. It assumes standard naming conventions for routes.

Requires Rails 3.

Example

Models:

# Columns:
#  name
#  column1
#  column2
#  secret
class Foo < ActiveRecord::Base
  has_many :bars
end

# Columns:
#  bar1
#  bar2
#  system
#  subbar1
#  subbar2
#  type
class Bar < ActiveRecord::Base
  has_one :foo
end

class SubBar1 < Bar
  def interesting_state; ... end
end

class SubBar2 < Bar
end

Example configuration (config/initializers/restful.rb:

# Required for href route generation. (This can also be set per web_service)
Restful.default_url_options(:host => 'foo.com')

Restful.register_web_service('Foo Web Service') do |config|

  # This is the url prefix used for calls to the web service.  It defaults to
  # the web service name, but can be set to be something different, or to
  # nil, if your web service has no base uri and named_routes
  # rely solely on the model class.
  config.api_prefix = 'foo_api'

  # This configuration provides information which anyone authorized to see a
  # given object at the most basic level should be able to see.
  # 
  # Note: it is advisable to set :serialization => :only for all models, so that
  # new attributes do not automatically become available through the api.
  config.register_resource(:foo,
    :serialization => {
      :only => [:id, :column1, :column2],
    },
    :associations => {:bars => nil}
  )

  config.register_resource(:bar,
    :serialization => {
      :only => [:id, :bar1, :bar2],
      :include => {
        :foo => { :only => [:column1] }
      },
    },
    :associations => {:foo => nil}
  )

  # Alternatively you may manipulate the resource configuration directly.
  # This can be helpful if you are inheriting properties from a base class and
  # want fine-grained control over how the options are merged and finalized.
  config.register_resource(:sub_bar1) do |resource|
    resource.serialization do |serial|
      serial.only << :subbar1 
      serial.methods << :interesting_state
    end
  end

  config.register_resource(:sub_bar2) do |resource|
    resource.serialization do |serial|
      serial.only << :subbar1
    end
    # If shallow is set false, then associations will be presented when the
    # resource is generated from lists (as in foo.bars.restful)
    resource.shallow = false
  end
end

Note that the serialization configuration is the same which you would normally pass to ActiveRecord::Serialization (in a model.to_json call, for instance).

Example output:

foo = Foo.create(:name => 'A foo', :column1 => 1, :column2 => 2, :secret => "very secret")
pp foo.restful('Foo Web Service')
# =>
# {"href"=>"http://test.app/client_api/foos/1",
#  "name"=>"A foo",
#  "bars_href"=>"http://test.app/client_api/foos/1/bars",
#  "foo"=>
#   {"id"=>1,
#    "name"=>"A foo",
#    "column1"=>1,
#    "column2"=>2,}}

pp foo.restful('Foo Web Service') do |configure|
  configure.serialization.only = [:id, :name]
end
# =>
# {"href"=>"http://test.app/client_api/foos/1",
#  "name"=>"A foo",
#  "bars_href"=>"http://test.app/client_api/foos/1/bars",
#  "foo"=>
#   {"id"=>1,
#    "name"=>"A foo",}}

More Docs

Please see the Restful rdoc and the specs for more details.

Rails 2

This gem requires Rails 3. To use it with Rails 2, you will need version 0.1.4, which is tagged ‘rails2’ in github.