Active Resource is only a small piece of a much larger puzzle. Active Resource is dependent on the remote web service conforming to the Rails RESTful URL structure and data serialization conventions. The web service does not have to be provided by a Rails application, but this is the most common case because Rails makes it so easy to create a RESTful, web service enabled application.

There are two benefits to understanding Active Resource. The first benefit is the ability to quickly and easily create an Active Resource client for someone else's web service. The second benefit is being able to easily expose your own application to Active Resource clients. We're going to take a look under the hood at the communication between an Active Resource client and a Rails application in order to build a complete understanding of web services in Rails.

Active Resource is able to easily consume a web service offered by Rails application conforming to a RESTful architecture because of the consistent URL layout and behavior Representational State Transfer (REST) imposes on the application. REST works with the concept of resources, which are sources of information that can be uniquely addressed by a URI. Clients of an application exchange representations of resources via HTTP. Multiple different representations of a single resource may be available from a single URI. In terms of Rails, multiple different formats of a resource are available from a single controller action, based on the format requested by the client. Active Resource works by specifically asking the Rails application for an XML or JSON representation of a resource, whereas a client's browser would request the HTML representation.

Another principle of REST is the use of a constrained set of well defined operations. In Rails, the well defined set of operations are based on the different HTTP verbs available. The HTTP verbs GET, POST, PUT, and DELETE map to the standard create, read, update, and delete (CRUD) operations offered by a Rails controller. Instead of specifying the operation to be performed through the request URI like show in /customers/show/15, a RESTful application would send an HTTP GET request to the resource's member URI /customers/15. A member URI, such as /customers/15, uniquely addresses an individual resource, whereas a collection URI, such as /customers, addresses the entire set of resources. Using the HTTP verb in conjunction with the resource URI to specify the desired operation eliminates redundancy and utilizes the well defined underlying HTTP protocol specifications.

Active Resource relies on the server providing the appropriate HTTP status code with each response. This allows Active Resource to accurately communicate any failure conditions that might occur. All status codes between 200 and 399 are considered successful, except for 301 and 302, which are redirects. One other exception is when the server returns the 422 Unprocessable Entity status code, which indicates that validation of the resource failed. In this case, Active Resource rescues the exception and parses the errors returned in the response body so that they are accessible to the client code. We'll take a closer look at validation and errors later in the chapter. Table 12.1, “Active Resource Exceptions” shows the exceptions raised for each different HTTP status code.

In the following sections we'll take a look at the code for the client and server, as well as how they interoperate with one another. This will help to solidify your understanding of Active Resource and your knowledge of how Rails uses REST and HTTP protocol conventions to simplify web services.

Let's construct a client for a RESTful Rails web service providing customer information. The web service application will be a simple Rails application consisting of a CustomersController and a Customer model. The client of the web service will be a simple Active Resource client named Api::Customer. The overall architecture of the client and server discussed in this section is shown in Figure 12.1, “High level overview of a RESTful Rails web service.”.

Figure 12.1. High level overview of a RESTful Rails web service.

module Api
  class Customer < ActiveResource::Base
    self.site = 'http://localhost:3000'
  end
end

class PersonResource < ActiveResource::Base
  self.element_name = "person"
end

ActiveResource::Base.logger = Rails.logger

GET http://localhost:3000/customers.xml
--> 200 OK 301 (93.2ms)
GET http://localhost:3000/customers/1.xml
--> 200 OK 141 (51.1ms)
POST http://localhost:3000/customers.xml
--> 201 Created 143 (164.5ms)
PUT http://localhost:3000/customers/4.xml
--> 200 OK 1 (94.6ms)

require 'rubygems'
require 'logger'
require 'active_resource'
require "active_resource/railties/log_subscriber"

ActiveResource::Base.logger = Logger.new(STDOUT)
ActiveResource::Base.logger.level = Logger::DEBUG

Rails::LogSubscriber.add(:active_resource, ActiveResource::Railties::LogSubscriber.new)

class Customer < ActiveResource::Base
  schema do
    attribute 'name', 'string'
    attribute 'age', 'integer'
  end
end

customer = Customer.new
customer.respond_to?(:name)  # => true
customer.respond_to?(:age)   # => true
customer.respond_to?(:title) # => false

class Customer < ActiveResource::Base
  schema do
    string 'name', 'company'
    integer 'age'
  end
end

Example::Application.routes.draw do |map|
  resources :customers do
    collection do
      get :oldest, :adults
    end
  end
end

class CustomersController < ApplicationController

  # GET /customers.xml
  def index
    @customers = Customer.find(:all)
    
    respond_to do |format|
      format.xml { render :xml => @customers }
    end
  end

  # GET /customers/1.xml
  def show
    @customer = Customer.find(params[:id])
    
    respond_to do |format|
     format.xml { render :xml => @customer }
    end
  end

  # POST /customers.xml
  def create
    @customer = Customer.new(params[:customer])
  
    respond_to do |format|
      if @customer.save
        format.xml do
          render :xml => @customer, :status => :created, :location => @customer
        end
      else
        format.xml do
          render :xml => @customer.errors, :status => :unprocessable_entity
        end
      end
    end
  end

  # PUT /customers/1.xml
  def update
    @customer = Customer.find(params[:id])

    respond_to do |format|
      if @customer.update_attributes(params[:customer])
        format.xml { head :ok }
      else
        format.xml do
          render :xml => @customer.errors, :status => :unprocessable_entity
        end
      end
    end
  end

  # DELETE /customers/1.xml
  def destroy
    @customer = Customer.find(params[:id])
    @customer.destroy

    respond_to do |format|
      format.xml { head :ok }
    end
  end
  
  # GET /customers/oldest.xml
  def oldest 
    @customer = Customer.find(:first, :order => 'age DESC')
    
    respond_to do |format|
      format.xml { render :xml => @customer }
    end
  end
  
  # GET /customers/adults.xml
  def adults
    @customers = Customer.find(:all, :conditions => 'age >= 18')
    
    respond_to do |format|
      format.xml { render :xml => @customers }
    end
  end
end

class Customer < ActiveRecord::Base
  validates_presence_of :name
  validates_numericality_of :age, :greater_than => 0
end

Active Resource reads resources by sending GET requests to the collection or member URLs of a resource. Any call to find that acts as a query will be sent to the collection URI of the resource because the exact resource isn't yet known. Finding a resource by ID sends the request to the member URI for the resource, since the exact desired resource is known.

customers = Api::Customer.find(:all)

GET /customers.xml HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>
<customers type="array">
  <customer>
    <age type="integer">30</age>
    <id type="integer">1</id>
    <name>Cody</name>
  </customer>
  <customer>
    <age type="integer">28</age>
    <id type="integer">2</id>
    <name>Tobi</name>
  </customer>
</customers>

[#<Api::Customer:0x105d2d9e8
  @attributes={"name"=>"Cody", "id"=>1, "age"=>30},
  @prefix_options={}>,
 #<Api::Customer:0x105d2d920
  @attributes={"name"=>"Tobi", "id"=>2, "age"=>28},
  @prefix_options={}>]

customer = customers.first
customer.id   # => 1
customer.name # => "Cody"
customer.age  # => 30
customer.new? # => false

customer = Api::Customer.find(1)

GET /customers/1.xml HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <age type="integer">30</age>
  <id type="integer">1</id>
  <name>Cody</name>
</customer>

customers = Api::Customer.find(:all, :from => :adults)

customer = Api::Customer.find(:one, :from => :oldest)

Active Resource creates a resource by sending a POST request containing the resource's attribute data to the collection URI of the resource. Creating a new resource looks very similar to the creation of a new record using Active Record. Like with Active Record, you can either build a new object with new and then call save on it, or make a single call to create.

customer = Api::Customer.new(:name => "Daniel", :age => 29)
customer.save

POST /customers.xml HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <name>Daniel</name>
  <age type="integer">29</age>
</customer>

Location: http://localhost/customers/3

render :nothing => true, :status => :created, :location => @customer

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <age type="integer">29</age>
  <id type="integer">3</id>
  <name>Daniel</name>
</customer>

class Customer < ActiveResource::Base
  schema do
    string 'name'
    integer 'age'
  end
  
  validates_presence_of :name
  validates_numericality_of :age, :greater_than_or_equal_to => 0
end

customer = Customer.new
customer.valid? # => false
customer.errors.full_messages
# => ["Name can't be blank", "Age is not a number"]

customer.name = "Max Fightmaster"
customer.age = 47
customer.valid? # => true

customer = Api::Customer.new(:name => "", :age => 0)
customer.save

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
  <error>Age must be greater than 0</error>
</errors>

customer.valid?                 # => false
customer.errors.empty?          # => false
customer.errors.size            # => 2
customer.errors.invalid?(:name) # => true
customer.errors.on(:name)       # => "can't be blank"
customer.errors.invalid?(:age)  # => true
customer.errors.on(:age)        # => "must be greater than 0"
customer.errors.full_messages  
# => ["Name can't be blank", "Age must be greater than 0"]

Active Resource updates a resource by sending a PUT request to the member URI of the resource.

Unlike with an Active Record object, it is possible to mass assign the ID of an Active Resource object. This allows a client to update a resource that it knows the ID of without having to first retrieve the resource from the remote server.

customer = Api::Customer.new(:id => 1, :age => 98)
customer.save

However, you'll probably find a resource first and then update it:

customer = Api::Customer.find(1)
customer.age = 98
customer.save

In the call to save, Active Resource sends a PUT request with the updated information for the resource to the resource's URI:

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <name>Cody</name>
  <id type="integer">1</id>
  <age type="integer">98</age>
</customer>

If the update is successful then the server will return the HTTP status code 200 OK with an empty response body.

If the update to the resource fails validation then the server will return the errors causing the validation failure along with the HTTP status code 422 Unprocessable Entity.

Active Resource deletes a resource by sending a DELETE request to the member URI of the resource. Deleting a resource can be done by calling the delete class method of the Active Resource model with the ID of the resource to be deleted:

Api::Customer.delete(1)

You can also call the destroy method on an instance of an Active Resource model:

customer = Api::Customer.find(1)
customer.destroy

Either way you choose to delete the resource, the same HTTP request will be made, which is a DELETE request to the resource's member URI:

DELETE /customers/1.xml HTTP/1.1

The destroy action shown in Example 12.2, “A simple controller providing a RESTful web service.” is the standard way of deleting a record. The action returns a 200 Ok with an empty response body.

The case may be that the standard Active Resource lifecycle methods are not sufficient for calling a custom operation on a resource. Fortunately, Active Resource models are able to make custom GET, POST, PUT, and DELETE requests to both member and collection URIs of a resource. ActiveResource::Base is extended with both class and instance methods for each HTTP verb: get, post, put, and delete.

The custom URI is formed by appending the name of the desired custom action to the collection or member URI. For a custom action on the resource's custom collection action oldest:

customer = Api::Customer.get(:oldest)

As we already saw in the section called “Finding resources from custom paths”, Active Resource sends an HTTP GET request to the /customers/oldest.xml URI. The same response is returned by the web service as before, however, the response is not automatically mapped to an instance of the Api::Customer class. Normally the response from an Active Resource lifecycle method is automatically mapped to an instance, or instances, of an Active Resource model, but this is not the case for custom requests. A response to a custom request is converted to a hash using Hash.from_xml. In this case the response is a single hash:

{"name"=>"Cody", "id"=>1, "age"=>30}

Active Resource supports HTTP basic access authentication. HTTP basic authentication allows the web service to authenticate the Active Resource client based on a set of credentials with each request to the web service. See ??? for more detailed information on adding HTTP basic authentication to your application. Any use of HTTP basic authentication needs to be performed over a secure SSL connection in order to protect the credentials and data transmitted.

Setting up the server to perform HTTP basic authentication can be as simple as adding a before filter to the controller:

class CustomersController < ApplicationController
  before_filter :authenticate

  private
  def authenticate
    authenticate_or_request_with_http_basic do |user_name, password| 
      user_name == "cody" && password == "secret"
    end
  end
end

The controller will attempt to authenticate the user with the user name cody and password secret or return an HTTP 401 Unauthorized status code.

To use Active Resource with a server that uses HTTP basic authentication you need to configure the credentials on the Active Resource model. As with most other configuration settings, the credentials are inherited to subclasses of ActiveResource::Base. This allows you to set the credentials once on ActiveResource::Base or on a particular subclass.

The credentials used by HTTP basic authentication are a user name and a password. There are two ways to provide the user name and password to be used. The first is to place the user name and password into the site using the http://user:password@host:port format:

module Api
  class Customer < ActiveResource::Base
    self.site = 'http://cody:secret@localhost:3000'
  end
end

The second way is to set the user and password class accessors. This method is useful for code clarity, but also if the user name you're using is an email address. The @ symbol in an email address will result in an invalid URI.

module Api
  class Customer < ActiveResource::Base
    self.site = 'http://localhost:3000'
    self.user = 'cody@example.com'
    self.password = 'secret'
  end
end

Once configured, Active Resource will provide the credentials to the server on each request. As was shown above, the server returns an HTTP 401 Unauthorized status code when the client cannot be authenticated. The 401 Unauthorized status code causes an ActiveResource::UnauthorizedAccess exception to be raised in the Active Resource client.