README.rdoc

Active Resource

Active Resource (ARes) connects business objects and Representational State
Transfer (REST) web services. It implements object-relational mapping for
REST web services to provide transparent proxying capabilities between a
client (ActiveResource) and a RESTful service (which is provided by Simply
RESTful routing in ActionController::Resources).

Philosophy

Active Resource attempts to provide a coherent wrapper object-relational
mapping for REST web services. It follows the same philosophy as Active
Record, in that one of its prime aims is to reduce the amount of code
needed to map to these resources. This is made possible by relying on a
number of code- and protocol-based conventions that make it easy for Active
Resource to infer complex relations and structures. These conventions are
outlined in detail in the documentation for ActiveResource::Base.

Overview

Model classes are mapped to remote REST resources by Active Resource much
the same way Active Record maps model classes to database tables. When a
request is made to a remote resource, a REST XML request is generated,
transmitted, and the result received and serialized into a usable Ruby
object.

Configuration and Usage

Putting Active Resource to use is very similar to Active Record. It's
as simple as creating a model class that inherits from ActiveResource::Base
and providing a site class variable to it:

As you can see, the methods are quite similar to Active Record's
methods for dealing with database records. But rather than dealing
directly with a database record, you're dealing with HTTP resources
(which may or may not be database records).

Protocol

Active Resource is built on a standard XML format for requesting and
submitting resources over HTTP. It mirrors the RESTful routing built into
Action Controller but will also work with any other REST service that
properly implements the protocol. REST uses HTTP, but unlike “typical” web
applications, it makes use of all the verbs available in the HTTP
specification:

GET requests are used for finding and retrieving resources.

POST requests are used to create new resources.

PUT requests are used to update existing resources.

DELETE requests are used to delete resources.

For more information on how this protocol works with Active Resource, see
the ActiveResource::Base documentation; for more general information on
REST web services, see the article here.

Find

Find requests use the GET method and expect the XML form of whatever
resource/resources is/are being requested. So, for a request for a single
element, the XML of that item is expected in response:

Create

Creating a new resource submits the XML form of the resource as the body of
the request and expects a 'Location' header in the response with
the RESTful URL location of the newly created resource. The id of the
newly created resource is parsed out of the Location response header and
automatically set as the id of the ARes object.

Update

'save' is also used to update an existing resource - and follows
the same protocol as creating a resource with the exception that no
response headers are needed - just an empty response when the update on the
server side was successful.