Class: ActiveResource::Base

Class | ActiveResource::Base
In: | lib/active_resource/base.rb
Parent: | Object

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/vendor/rails/activeresource/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. In the case where you already have an existing model with the same name as the desired RESTful resource you can set the `element_name` value.

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

## 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 created 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. To invoke them, Active Resource provides the `get`, `post`, `put` and `delete` methods where you can specify a custom REST method name to invoke.

      # POST to the custom 'register' REST method, i.e. POST /people/new/register.xml.
      Person.new(:name => 'Ryan').post(:register)
      # => { :id => 1, :name => 'Ryan', :position => 'Clerk' }

      # PUT an update by invoking the 'promote' REST method, i.e. PUT /people/1/promote.xml?position=Manager.
      Person.find(1).put(:promote, :position => 'Manager')
      # => { :id => 1, :name => 'Ryan', :position => 'Manager' }

      # GET all the positions available, i.e. GET /people/positions.xml.
      Person.get(:positions)
      # => [{:name => 'Manager'}, {:name => 'Clerk'}]

      # DELETE to 'fire' a person, i.e. DELETE /people/1/fire.xml.
      Person.find(1).delete(:fire)

For more information on 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 URL for the `site` variable.

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

- defining `user` and/or `password` variables

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

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

Note: Some values cannot be provided in the URL passed to site. e.g. email addresses as usernames. In those situations you should use the seperate user and password option.

## 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) # 404, raises ActiveResource::ResourceNotFound

`404` is just one of the HTTP error response codes that Active Resource 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 type="array"><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.

### Timeouts

Active Resource relies on HTTP to access RESTful APIs and as such is inherently susceptible to slow or unresponsive servers. In such cases, your Active Resource method calls could timeout. You can control the amount of time before Active Resource times out with the `timeout` variable.

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

This sets the `timeout` to 5 seconds. You can adjust the `timeout` to a value suitable for the RESTful API you are accessing. It is recommended to set this to a reasonably low value to allow your Active Resource clients (especially if you are using Active Resource in a Rails application) to fail-fast (see en.wikipedia.org/wiki/Fail-fast) rather than cause cascading failures that could incapacitate your server.

When a timeout occurs, an ActiveResource::TimeoutError is raised. You should rescue from ActiveResource::TimeoutError in your Active Resource method calls.

Internally, Active Resource relies on Ruby‘s Net::HTTP library to make HTTP requests. Setting `timeout` sets the `read_timeout` of the internal Net::HTTP instance to the same value. The default `read_timeout` is 60 seconds on most Ruby implementations.

### Methods

== clone collection_path collection_path connection connection create create delete destroy dup element_path element_path eql? exists? exists? find format= hash headers id id= id_from_response load load_attributes_from_response new new? password password= prefix prefix= prefix_source reload respond_to? save site site= timeout timeout= to_param to_xml update user user=

### 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

connection(refresh = false)

An instance of ActiveResource::Connection that is the base connection to the remote service. The `refresh` parameter toggles whether or not the connection is refreshed at every request or not (defaults to `false`).

create(attributes = {})

Create a new resource instance and request to the remote service that it be saved, making it equivalent to the following simultaneous calls:

      ryan = Person.new(:first => 'ryan')
      ryan.save

The newly created resource is returned. If a failure has occurred an exception will be raised (see save). If the resource is invalid and has not been saved then valid? will return `false`, while new? will still return `true`.

#### Examples

      Person.create(:name => 'Jeremy', :email => 'myname@nospam.com', :enabled => true)
      my_person = Person.find(:first)
      my_person.email # => myname@nospam.com

      dhh = Person.create(:name => 'David', :email => 'dhh@nospam.com', :enabled => true)
      dhh.valid? # => true
      dhh.new?   # => false

      # We'll assume that there's a validation that requires the name attribute
      that_guy = Person.create(:name => '', :email => 'thatguy@nospam.com', :enabled => true)
      that_guy.valid? # => false
      that_guy.new?   # => true

delete(id, options = {})

Deletes the resources with the ID in the `id` parameter.

#### Options

All options specify prefix and query parameters.

#### Examples

      Event.delete(2) # sends DELETE /events/2

      Event.create(:name => 'Free Concert', :location => 'Community Center')
      my_event = Event.find(:first) # let's assume this is event with ID 7
      Event.delete(my_event.id) # sends DELETE /events/7

      # Let's assume a request to events/5/cancel.xml
      Event.delete(params[:id]) # sends DELETE /events/5

element_path(id, prefix_options = {}, query_options = nil)

Gets the element path for the given ID in `id`. 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 URLs (e.g., `:account_id => 19`

                       would yield a URL like <tt>/accounts/19/purchases.xml</tt>).

`query_options` - A hash to add items to the query string for the request.

#### Examples

      Post.element_path(1)
      # => /posts/1.xml

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

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

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

exists?(id, options = {})

Asserts the existence of a resource, returning `true` if the resource is found.

#### Examples

      Note.create(:title => 'Hello, world.', :body => 'Nothing more for now...')
      Note.exists?(1) # => true

      Note.exists(1349) # => false

find(*arguments)

Core method for finding resources. Used similarly to Active Record‘s `find` method.

#### Arguments

The first argument is considered to be the scope of the query. That is, how many resources are returned from the request. It can be one of the following.

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

#### Options

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

#### Examples

      Person.find(1)
      # => GET /people/1.xml

      Person.find(:all)
      # => GET /people.xml

      Person.find(:all, :params => { :title => "CEO" })
      # => GET /people.xml?title=CEO

      Person.find(:first, :from => :managers)
      # => GET /people/managers.xml

      Person.find(:all, :from => "/companies/1/people.xml")
      # => GET /companies/1/people.xml

      Person.find(:one, :from => :leader)
      # => GET /people/leader.xml

      Person.find(:all, :from => :developers, :params => { :language => 'ruby' })
      # => GET /people/developers.xml?language=ruby

      Person.find(:one, :from => "/companies/1/manager.xml")
      # => GET /companies/1/manager.xml

      StreetAddress.find(1, :params => { :person_id => 1 })
      # => GET /people/1/street_addresses/1.xml

format=(mime_type_reference_or_format)

Sets the format that attributes are sent and received in from a mime type reference:

      Person.format = :json
      Person.find(1) # => GET /people/1.json

      Person.format = ActiveResource::Formats::XmlFormat
      Person.find(1) # => GET /people/1.xml

Default format is `:xml`.

headers()
new(attributes = {})

Constructor method for new resources; the optional `attributes` parameter takes a hash of attributes for the new resource.

#### Examples

      my_course = Course.new
      my_course.name = "Western Civilization"
      my_course.lecturer = "Don Trotter"
      my_course.save

      my_other_course = Course.new(:name => "Philosophy: Reason and Being", :lecturer => "Ralph Cling")
      my_other_course.save

password()

Gets the password for REST HTTP authentication.

password=(password)

Sets the password for REST HTTP authentication.

prefix(options={})

Gets the prefix for a resource‘s nested URL (e.g., `prefix/collectionname/1.xml`) This method is regenerated at runtime based on what the prefix is set to.

prefix=(value = '/')

Sets the prefix for a resource‘s nested URL (e.g., `prefix/collectionname/1.xml`). Default value is `site.path`.

prefix_source()

An attribute reader for the source string for the resource path prefix. This method is regenerated at runtime based on what the prefix is set to.

site()

Gets the URI of the REST resources to map for this class. The site variable is required Active Resource‘s mapping to work.

site=(site)

Sets the URI of the REST resources to map for this class to the value in the `site` argument. The site variable is required Active Resource‘s mapping to work.

timeout()

Gets tthe number of seconds after which requests to the REST API should time out.

timeout=(timeout)

Sets the number of seconds after which requests to the REST API should time out.

user()

Gets the user for REST HTTP authentication.

user=(user)

Sets the user for REST HTTP authentication.

### Public Instance methods

==(other)

Test for equality. Resource are equal if and only if `other` is the same object or is an instance of the same class, is not `new?`, and has the same `id`.

#### Examples

      ryan = Person.create(:name => 'Ryan')
      jamie = Person.create(:name => 'Jamie')

      ryan == jamie
      # => false (Different name attribute and id)

      ryan_again = Person.new(:name => 'Ryan')
      ryan == ryan_again
      # => false (ryan_again is new?)

      ryans_clone = Person.create(:name => 'Ryan')
      ryan == ryans_clone
      # => false (Different id attributes)

      ryans_twin = Person.find(ryan.id)
      ryan == ryans_twin
      # => true

clone()

Returns a clone of the resource that hasn‘t been assigned an `id` yet and is treated as a new resource.

      ryan = Person.find(1)
      not_ryan = ryan.clone
      not_ryan.new?  # => true

Any active resource member attributes will NOT be cloned, though all other attributes are. This is to prevent the conflict between any `prefix_options` that refer to the original parent resource and the newly cloned parent resource that does not exist.

      ryan = Person.find(1)
      ryan.address = StreetAddress.find(1, :person_id => ryan.id)
      ryan.hash = {:not => "an ARes instance"}

      not_ryan = ryan.clone
      not_ryan.new?            # => true
      not_ryan.address         # => NoMethodError
      not_ryan.hash            # => {:not => "an ARes instance"}

destroy()

Deletes the resource from the remote service.

#### Examples

      my_id = 3
      my_person = Person.find(my_id)
      my_person.destroy
      Person.find(my_id) # 404 (Resource Not Found)

      new_person = Person.create(:name => 'James')
      new_id = new_person.id # => 7
      new_person.destroy
      Person.find(new_id) # 404 (Resource Not Found)

dup()

Duplicate the current resource without saving it.

#### Examples

      my_invoice = Invoice.create(:customer => 'That Company')
      next_invoice = my_invoice.dup
      next_invoice.new? # => true

      next_invoice.save
      next_invoice == my_invoice # => false (different id attributes)

      my_invoice.customer   # => That Company
      next_invoice.customer # => That Company

eql?(other)

Tests for equality (delegates to ==).

exists?()

Evaluates to `true` if this resource is not `new?` and is found on the remote service. Using this method, you can check for resources that may have been deleted between the object‘s instantiation and actions on it.

#### Examples

      Person.create(:name => 'Theodore Roosevelt')
      that_guy = Person.find(:first)
      that_guy.exists? # => true

      that_lady = Person.new(:name => 'Paul Bean')
      that_lady.exists? # => false

      guys_id = that_guy.id
      Person.delete(guys_id)
      that_guy.exists? # => false

hash()

Delegates to id in order to allow two resources of the same type and id to work with something like:

      [Person.find(1), Person.find(2)] & [Person.find(1), Person.find(4)] # => [Person.find(1)]

id()

Get the `id` attribute of the resource.

id=(id)

Set the `id` attribute of the resource.

load(attributes)

A method to manually load attributes from a hash. Recursively loads collections of resources. This method is called in `initialize` and `create` when a hash of attributes is provided.

#### Examples

      my_attrs = {:name => 'J&J Textiles', :industry => 'Cloth and textiles'}

      the_supplier = Supplier.find(:first)
      the_supplier.name # => 'J&M Textiles'
      the_supplier.load(my_attrs)
      the_supplier.name('J&J Textiles')

      # These two calls are the same as Supplier.new(my_attrs)
      my_supplier = Supplier.new
      my_supplier.load(my_attrs)

      # These three calls are the same as Supplier.create(my_attrs)
      your_supplier = Supplier.new
      your_supplier.load(my_attrs)
      your_supplier.save

new?()

A method to determine if the resource a new object (i.e., it has not been POSTed to the remote service yet).

#### Examples

      not_new = Computer.create(:brand => 'Apple', :make => 'MacBook', :vendor => 'MacMall')
      not_new.new? # => false

      is_new = Computer.new(:brand => 'IBM', :make => 'Thinkpad', :vendor => 'IBM')
      is_new.new? # => true

      is_new.save
      is_new.new? # => false

reload()

A method to reload the attributes of this object from the remote web service.

#### Examples

      my_branch = Branch.find(:first)
      my_branch.name # => "Wislon Raod"

      # Another client fixes the typo...

      my_branch.name # => "Wislon Raod"
      my_branch.reload
      my_branch.name # => "Wilson Road"

respond_to?(method, include_priv = false)

A method to determine if an object responds to a message (e.g., a method call). In Active Resource, a Person object with a `name` attribute can answer `true` to `my_person.respond_to?("name")`, `my_person.respond_to?("name=")`, and `my_person.respond_to?("name?")`.

save()

A method to save (`POST`) or update (`PUT`) a resource. It delegates to `create` if a new object, `update` if it is existing. If the response to the save includes a body, it will be assumed that this body is XML for the final object as it looked after the save (which would include attributes like `created_at` that weren‘t part of the original submit).

#### Examples

      my_company = Company.new(:name => 'RoleModel Software', :owner => 'Ken Auer', :size => 2)
      my_company.new? # => true
      my_company.save # sends POST /companies/ (create)

      my_company.new? # => false
      my_company.size = 10
      my_company.save # sends PUT /companies/1 (update)

to_param()

Allows Active Resource objects to be used as parameters in Action Pack URL generation.

to_xml(options={})

A method to convert the the resource to an XML string.

#### Options

The `options` parameter is handed off to the `to_xml` method on each attribute, so it has the same options as the `to_xml` methods in Active Support.

- `: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`).

#### Examples

      my_group = SubsidiaryGroup.find(:first)
      my_group.to_xml
      # => <?xml version="1.0" encoding="UTF-8"?>
      #    <subsidiary_group> [...] </subsidiary_group>

      my_group.to_xml(:dasherize => true)
      # => <?xml version="1.0" encoding="UTF-8"?>
      #    <subsidiary-group> [...] </subsidiary-group>

      my_group.to_xml(:skip_instruct => true)
      # => <subsidiary_group> [...] </subsidiary_group>

### Protected Instance methods

collection_path(options = nil)
connection(refresh = false)
create()

Create (i.e., save to the remote service) the new resource.

element_path(options = nil)
id_from_response(response)

Takes a response from a typical create post and pulls the ID out

load_attributes_from_response(response)
update()

Update the resource on the remote service.

[Validate]