Class: ActiveResource::Base

ActiveResource::Base is the main class for mapping RESTful resources as models in a Rails application.

For an outline of what Active Resource is capable of, see files/README.html.

Automated mapping

Active Resource objects represent your RESTful resources as manipulatable Ruby objects. To map resources to Ruby objects, Active Resource only needs a class name that corresponds to the resource name (e.g., the class Person maps to the resources people, very similarly to Active Record) and a site value, which holds the URI of the resources.

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

Now the Person class is mapped to RESTful resources located at api.people.com:3000/people/, and you can now use Active Resource’s lifecycles methods to manipulate resources.

Lifecycle methods

Active Resource exposes methods for creating, finding, updating, and deleting resources from REST web services.

  ryan = Person.new(:first => 'Ryan', :last => 'Daigle')
  ryan.save  #=> true
  ryan.id  #=> 2
  Person.exists?(ryan.id)  #=> true
  ryan.exists?  #=> true

  ryan = Person.find(1)
  # => Resource holding our newly create Person object

  ryan.first = 'Rizzle'
  ryan.save  #=> true

  ryan.destroy  #=> true

As you can see, these are very similar to Active Record’s lifecycle methods for database records. You can read more about each of these methods in their respective documentation.

Custom REST methods

Since simple CRUD/lifecycle methods can’t accomplish every task, Active Resource also supports defining your own custom REST methods.

  Person.new(:name => 'Ryan).post(:register)
  # => { :id => 1, :name => 'Ryan', :position => 'Clerk' }

  Person.find(1).put(:promote, :position => 'Manager')
  # => { :id => 1, :name => 'Ryan', :position => 'Manager' }

For more information on creating and using custom REST methods, see the ActiveResource::CustomMethods documentation.

Validations

You can validate resources client side by overriding validation methods in the base class.

    class Person < ActiveResource::Base
       self.site = "http://api.people.com:3000/"
       protected
         def validate
           errors.add("last", "has invalid characters") unless last =~ /[a-zA-Z]*/
         end
    end

See the ActiveResource::Validations documentation for more information.

Authentication

Many REST APIs will require authentication, usually in the form of basic HTTP authentication. Authentication can be specified by putting the credentials in the site variable of the Active Resource class you need to authenticate.

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

For obvious security reasons, it is probably best if such services are available over HTTPS.

Errors & Validation

Error handling and validation is handled in much the same manner as you’re used to seeing in Active Record. 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/999.xml
  ryan = Person.find(999) # => Raises ActiveResource::ResourceNotFound
  # => Response = 404

+404+ is just one of the HTTP error response codes that ActiveResource will handle with its own exception. The following HTTP response codes will also 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

These custom exceptions allow you to deal with resource errors more naturally and with more precision rather than returning a general HTTP error. For example:

  begin
    ryan = Person.find(my_id)
  rescue ActiveResource::ResourceNotFound
    redirect_to :action => 'not_found'
  rescue ActiveResource::ResourceConflict, ActiveResource::ResourceInvalid
    redirect_to :action => 'new'
  end

Validation errors

Active Resource supports validations on resources and will return errors if any these validations fail (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by a response code of +422+ and an 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.

  ryan = Person.find(1)
  ryan.first #=> ''
  ryan.save  #=> false

  # When
  # PUT http://api.people.com:3000/people/1.xml
  # is requested with invalid values, the response is:
  #
  # Response (422):
  # <errors><error>First cannot be empty</error></errors>
  #

  ryan.errors.invalid?(:first)  #=> true
  ryan.errors.full_messages  #=> ['First cannot be empty']

Learn more about Active Resource’s validation features in the ActiveResource::Validations documentation.

Methods

== collection_path collection_path connection connection create create create_site_uri_from delete destroy dup element_path element_path eql? exists? exists? find find_every find_one find_or_create_resource_for find_or_create_resource_for_collection find_single format= hash headers id id= id_from_response instantiate_collection instantiate_record load load_attributes_from_response new new? prefix prefix= prefix_parameters prefix_source query_string reload respond_to? save site site= split_options split_options to_xml update

External Aliases

prefix=	->	set_prefix
element_name=	->	set_element_name
collection_name=	->	set_collection_name
primary_key=	->	set_primary_key
respond_to?	->	respond_to_without_attributes?
	For checking respond_to? without searching the attributes (which is faster).

Public Class methods

collection_path(prefix_options = {}, query_options = nil)

Gets the collection path for the REST resources. If the query_options parameter is omitted, Rails will split from the prefix_options.

Options

`prefix_options`:	A hash to add a prefix to the request for nested URL’s (e.g., `:account_id => 19` would yield a URL like `/accounts/19/purchases.xml`).
`query_options`:	A hash to add items to the query string for the request.

Examples

  Post.collection_path
  # => /posts.xml

  Comment.collection_path(:post_id => 5)
  # => /posts/5/comments.xml

  Comment.collection_path(:post_id => 5, :active => 1)
  # => /posts/5/comments.xml?active=1

  Comment.collection_path({:post_id => 5}, {:active => 1})
  # => /posts/5/comments.xml?active=1

+:one+:	Returns a single resource.
+:first+:	Returns the first resource found.
+:all+:	Returns every resource that matches the request.

`from`:	Sets the path or custom method that resources will be fetched from.
`params`:	Sets query and prefix (nested URL) parameters.

indent:	Set the indent level for the XML output (default is +2+).
dasherize:	Boolean option to determine whether or not element names should replace underscores with dashes (default is `false`).
skip_instruct:	Toggle skipping the +instruct!+ call on the XML builder that generates the XML declaration (default is `false`).

Automated mapping

Lifecycle methods

Custom REST methods

Validations

Authentication

Errors & Validation

Resource errors

Validation errors

Methods

External Aliases

Public Class methods

Options

Examples

Examples

Options

Examples

Options

Examples

Examples

Arguments

Options

Examples

Examples

Private Class methods

Public Instance methods

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Options

Examples

Protected Instance methods

Private Instance methods