benjaminkrause-restful

Disclaimer

!!! Refactor this shice. Seriously, this has devolved into some nasty-ass code.

Why?

Aims to provide a production quality Rest API to your Rails app, with the following features:

• whitelisting
• flexible xml formats with good defaults
• all resources are referred to by url and not by id; expose a "web of resources"

Serializers

Getting started

In order to make your models apiable add

apiable

to your model. Next, define which properties you want to export, so within the model write something like:

self.restful_publish(:name, :current-location, :pets)

Configuration

Some example configurations:

Person

restful_publish :name, :pets, :restful_options => { :expansion => :expanded } # default on level 1-2: expanded. default above: collapsed. restful_publish :name, :pets, :wallet => :contents, :restful_options => { :expansion => :expanded } # combined options and expansion rules restful_publish :name, :pets, :restful_options => { :collapsed => :pets } # collapsed pets, even though they are on the second level. restful_publish :name, :pets, :restful_options => { :force_expanded => [:pets, :wallet] }

Pet

restful_publish :name, :person # expands person per default because it is on the second level. Does not expand person.pets.first.person, since this is higher than second level.

Options

You can add includes to your call like this:

pet.to_restful_json :include => :owner.

Rails-like

This format sticks to xml_simple, adding links as <association-name-restful-url> nodes of type "link".

Person.last.to_restful.serialize(:xml) OR Person.last.to_restful_xml results in something like...

http://example.com:3000/people/1 Joe Bloggs Under a tree http://example.com:3000/pets/1 http://example.com:3000/people/1 http://example.com:3000/sexes/1 male

Atom-like

Person.last.to_restful.serialize(:atom_like) OR Person.last.to_restful_atom_like results in something like...

Joe Bloggs Under a tree male

Params-like

Person.last.to_restful.serialize(:params) OR Person.last.to_restful_params results in something like...

{:sex_attributes => {:sex=>"male"}, :current_location=>"Under a tree", :name=>"Joe Bloggs", :pets_attributes=> [ {:person_id=>1, :name=>nil} ] }

Other Serializers

Hash. Spits out a plain ole hash, no nested attributes or such like. Useful for further conversions.

Deserializing

Use Restful.from_atom_like(xml).serialize(:hash) to convert from an atom-like formatted xml create to a params hash. Takes care of dereferencing the urls back to ids. Generally, use Restful.from_<serializer name>(xml) to get a Resource.

Nested Attributes

Serializing uses Rails 2.3 notation of nested attributes. For deserializing you will need Rails 2.3 for having nested attributes support and the respective model must have the accepts_nested_attributes_for :<table name> set accordingly.