Permalink
Browse files

Big documentation upgrade for ARes (closes #8694) [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7098 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
dhh committed Jun 23, 2007
1 parent 753cbf1 commit ae4838fff20857b11b1092d82b34ef7d32edfcab
View
@@ -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.
Oops, something went wrong.

0 comments on commit ae4838f

Please sign in to comment.