Working With Rails

Active Resource

= Active Resource—Object-oriented REST services

Active Resource (ARes) connects business objects and REST web services. It is a library intended to provide transparent proxying capabilities between a client and a RESTful service (for which Rails provides the {Simply RESTful routing}[http://dev.rubyonrails.org/browser/trunk/actionpack/lib/action_controller/resources.rb] implementation).

=== Configuration & Usage

Configuration is as simple as inheriting from ActiveResource::Base and providing a site class variable:

class Person < ActiveResource::Base
  self.site = "http://api.people.com:3000/" 
end

Person is now REST enable and can invoke REST services very similarly to how ActiveRecord invokes lifecycle methods that operate against a persistent store.

1. Find a person with id = 1
2. This will invoke the following Http call:
3. GET http://api.people.com:3000/people/1.xml
4. and will load up the XML response into a new
5. Person object # ryan = Person.find(1) Person.exists?(1) #=> true

1. To create a new person – instantiate the object and call ‘save’,
2. which will invoke this Http call:
3. POST http://api.people.com:3000/people.xml
4. (and will submit the XML format of the person object in the request) # ryan = Person.new(:first => ‘Ryan’, :last => ‘Daigle’) ryan.save #=> true ryan.id #=> 2 Person.exists?(ryan.id) #=> true ryan.exists? #=> true

1. Resource creation can also use the convenience create method which
2. will request a resource save after instantiation. ryan = Person.create(:first => ‘Ryan’, :last => ‘Daigle’) ryan.exists? #=> true

1. Updating is done with ‘save’ as well
2. PUT http://api.people.com:3000/people/1.xml # ryan = Person.find(1) ryan.first = ‘Rizzle’ ryan.save #=> true

1. And destruction
2. DELETE http://api.people.com:3000/people/1.xml # ryan = Person.find(1) ryan.destroy #=> true # Or Person.delete(ryan.id)

=== Protocol

ARes is built on a standard XML format for requesting and submitting resources. It mirrors the RESTful routing built into ActionController, though it’s useful to discuss what ARes expects outside the context of ActionController as it is not dependent on a Rails-based RESTful implementation.

==== Find

GET Http requests 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:

1. Expects a response of #
2. <person><id>1</id><attribute1>value1</attribute1><attribute2>..</attribute2></person> #
3. for GET http://api.people.com:3000/people/1.xml # ryan = Person.find(1)

The XML document that is received is used to build a new object of type Person, with each XML element becoming an attribute on the object.

ryan.is_a? Person  #=> true
ryan.attribute1  #=> 'value1'

Any complex element (one that contains other elements) becomes its own object:

1. With this response: #
2. <person><id>1</id><attribute1>value1</attribute1><complex><attribute2>value2</attribute2></complex></person> #
3. for GET http://api.people.com:3000/people/1.xml # ryan = Person.find(1) ryan.complex #=> <person::complex::xxxxx> ryan.complex.attribute2 #=> ‘value2’

Collections can also be requested in a similar fashion

1. Expects a response of #
2. <people>
3. <person><id>1</id><first>Ryan</first></person>
4. <person><id>2</id><first>Jim</first></person>
5. </people> #
6. for GET http://api.people.com:3000/people.xml # people = Person.find(:all) people.first #=> <person::xxx> ‘Ryan’ ...> people.last #=> <person::xxx> ‘Jim’ ...>

==== 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.

1. <person><first>Ryan</first></person> #
2. is submitted as the body on #
3. POST http://api.people.com:3000/people.xml
5. when save is called on a new Person object. An empty response is
6. is expected with a ‘Location’ header value: #
7. Response (201): Location: http://api.people.com:3000/people/2 # ryan = Person.new(:first => ‘Ryan’) ryan.new? #=> true ryan.save #=> true ryan.new? #=> false ryan.id #=> 2

==== 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.

1. <person><first>Ryan</first></person> #
2. is submitted as the body on #
3. PUT http://api.people.com:3000/people/1.xml #
4. when save is called on an existing Person object. An empty response is
5. is expected with code (204) # ryan = Person.find(1) ryan.first #=> ‘Ryan’ ryan.first = ‘Rizzle’ ryan.save #=> true

==== Delete

Destruction of a resource can be invoked as a class and instance method of the resource.

1. A request is made to #
2. DELETE http://api.people.com:3000/people/1.xml #
3. for both of these forms. An empty response with
4. is expected with response code (200) # ryan = Person.find(1) ryan.destroy #=> true ryan.exists? #=> false Person.delete(2) #=> true Person.exists?(2) #=> false

=== Errors & Validation

Error handling and validation is handled in much the same manner as you’re used to seeing in ActiveRecord. Both the response code in the Http response and the body of the response are used to indicate that an error occurred.

==== Resource errors

When a get is requested for a resource that does not exist, the Http ‘404’ (resource not found) response code will be returned from the server which will raise an ActiveResource::ResourceNotFound exception.

1. GET http://api.people.com:3000/people/1.xml
2. #=> Response (404) # ryan = Person.find(1) #=> Raises ActiveResource::ResourceNotFound

==== Validation errors

Creating and updating resources can lead to validation errors – i.e. ‘First name cannot be empty’ etc… These types of errors are denoted in the response by a response code of 422 and the xml representation of the validation errors. The save operation will then fail (with a ‘false’ return value) and the validation errors can be accessed on the resource in question.

1. When #
2. PUT http://api.people.com:3000/people/1.xml #
3. is requested with invalid values, the expected response is: #
4. Response (422):
5. <errors><error>First cannot be empty</error></errors> # ryan = Person.find(1) ryan.first #=> ’’ ryan.save #=> false ryan.errors.invalid?(:first) #=> true ryan.errors.full_messages #=> [‘First cannot be empty’]

==== Response errors

If the underlying Http request for an ARes operation results in an error response code, an exception will be raised. The following Http response codes will result in these exceptions:

200 - 399: Valid response, no exception
404: ActiveResource::ResourceNotFound
409: ActiveResource::ResourceConflict
422: ActiveResource::ResourceInvalid (rescued by save as validation errors)
401 - 499: ActiveResource::ClientError
500 - 599: ActiveResource::ServerError

=== Authentication

Many REST apis will require username/password authentication, usually in the form of Http authentication. This can easily be specified by putting the username and password in the Url of the ARes site:

class Person < ActiveResource::Base
  self.site = "http://ryan:password@api.people.com:3000/" 
end

For obvious reasons it is best if such services are available over https.

NOTE: This description has been extracted from the Plugin README and so the formatting may need updating to make browser friendly