diff options
Diffstat (limited to 'activeresource/README')
| -rw-r--r-- | activeresource/README | 144 |
1 files changed, 37 insertions, 107 deletions
diff --git a/activeresource/README b/activeresource/README index 696b5e4fed..042af28e06 100644 --- a/activeresource/README +++ b/activeresource/README @@ -1,65 +1,57 @@ -= Active Resource -- Object-oriented REST services += Active Resource -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). +Active Resource (ARes) connects business objects and Representational State Transfer (REST) +web services. It implements object-relational mapping for REST webservices to provide transparent +proxying capabilities between a client (ActiveResource) and a RESTful service (which is provided by Simply RESTful routing +in ActionController::Resources). -=== Configuration & Usage +== Philosophy -Configuration is as simple as inheriting from ActiveResource::Base and providing a site -class variable: +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 ActiveResource to use is very similar to ActiveRecord. It's as simple as creating a model class +that inherits from ActiveResource::Base and providing a <tt>site</tt> class variable to it: 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 +Now the Person class is REST enabled and can invoke REST services very similarly to how ActiveRecord invokes lifecycle methods that operate against a persistent store. # Find a person with id = 1 - # This will invoke the following Http call: - # GET http://api.people.com:3000/people/1.xml - # and will load up the XML response into a new - # Person object - # ryan = Person.find(1) Person.exists?(1) #=> true - # To create a new person - instantiate the object and call 'save', - # which will invoke this Http call: - # POST http://api.people.com:3000/people.xml - # (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 - - # Resource creation can also use the convenience <tt>create</tt> method which - # will request a resource save after instantiation. - ryan = Person.create(:first => 'Ryan', :last => 'Daigle') - ryan.exists? #=> true - - # Updating is done with 'save' as well - # PUT http://api.people.com:3000/people/1.xml - # - ryan = Person.find(1) - ryan.first = 'Rizzle' - ryan.save #=> true +As you can see, the methods are quite similar to Active Record's methods for dealing with database +records. But rather than dealing with - # And destruction - # DELETE http://api.people.com:3000/people/1.xml - # - ryan = Person.find(1) - ryan.destroy #=> true # Or Person.delete(ryan.id) +==== Protocol +Active Resource is built on a standard XML format for requesting and submitting resources over HTTP. It mirrors the RESTful routing +built into ActionController 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: -=== Protocol +* 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. -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. +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[http://en.wikipedia.org/wiki/Representational_State_Transfer]. ==== Find @@ -169,67 +161,5 @@ Destruction of a resource can be invoked as a class and instance method of the r 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. - - # GET http://api.people.com:3000/people/1.xml - # #=> 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. - - # When - # - # PUT http://api.people.com:3000/people/1.xml - # - # is requested with invalid values, the expected response is: - # - # Response (422): - # <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 +You can find more usage information in the ActiveResource::Base documentation. -For obvious reasons it is best if such services are available over https. |