openskies 0.0.1

data/guides/source/active_resource_basics.textile

@@ -0,0 +1,120 @@
+h2. Active Resource Basics
+
+This guide should provide you with all you need to get started managing the connection between business objects and RESTful web services. It implements a way to map web-based resources to local objects with CRUD semantics.
+
+endprologue.
+
+WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails.
+
+h3. Introduction
+
+Active Resource allows you to connect with RESTful web services. So, in Rails, Resource classes inherited from +ActiveResource::Base+ and live in  +app/models+.
+
+h3. Configuration and Usage
+
+Putting Active Resource to use is very similar to Active Record.  It's as simple as creating a model class
+that inherits from ActiveResource::Base and providing a <tt>site</tt> class variable to it:
+
+<ruby>
+class Person < ActiveResource::Base
+  self.site = "http://api.people.com:3000/"
+end
+</ruby>
+
+Now the Person class is REST enabled and can invoke REST services very similarly to how Active Record invokes
+life cycle methods that operate against a persistent store.
+
+h3. Reading and Writing Data
+
+Active Resource make request over HTTP using a standard JSON format. It mirrors the RESTful routing built into Action Controller but will also work with any other REST service that properly implements the protocol.
+
+h4. Read
+
+Read requests use the GET method and expect the JSON form of whatever resource/resources is/are being requested.
+
+<ruby>
+# Find a person with id = 1
+person = Person.find(1)
+# Check if a person exists with id = 1
+Person.exists?(1)  # => true
+# Get all resources of Person class
+Person.all
+</ruby>
+
+h4. Create
+
+Creating a new resource submits the JSON form of the resource as the body of the request with HTTP POST method and parse the response into Active Resource object.
+
+<ruby>
+person = Person.create(:name => 'Vishnu')
+person.id  # => 1
+</ruby>
+
+h4. Update
+
+To update an existing resource, 'save' method is used. This method make a HTTP PUT request in JSON format.
+
+<ruby>
+person = Person.find(1)
+person.name = 'Atrai'
+person.save
+</ruby>
+
+h4. Delete
+
+'destroy' method makes a HTTP DELETE request for an existing resource in JSON format to delete that resource.
+
+<ruby>
+person = Person.find(1)
+person.destroy
+</ruby>
+
+h3. Validations
+
+Module to support validation and errors with Active Resource objects. The module overrides Base#save to rescue ActiveResource::ResourceInvalid exceptions and parse the errors returned in the web service response. The module also adds an errors collection that mimics the interface of the errors provided by ActiveModel::Errors.
+
+h4. Validating client side resources by overriding validation methods in base class
+
+<ruby>
+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
+</ruby>
+
+h4. Validating client side resources
+
+Consider a Person resource on the server requiring both a first_name and a last_name with a validates_presence_of :first_name, :last_name declaration in the model:
+
+<ruby>
+person = Person.new(:first_name => "Jim", :last_name => "")
+person.save                   # => false (server returns an HTTP 422 status code and errors)
+person.valid?                 # => false
+person.errors.empty?          # => false
+person.errors.count           # => 1
+person.errors.full_messages   # => ["Last name can't be empty"]
+person.errors[:last_name]  # => ["can't be empty"]
+person.last_name = "Halpert"
+person.save                   # => true (and person is now saved to the remote service)
+</ruby>
+
+h4. Public instance methods
+
+ActiveResource::Validations have three public instance methods
+
+h5. errors()
+
+This will return errors object that holds all information about attribute error messages
+
+h5. save_with_validation(options=nil)
+
+This validates the resource with any local validations written in base class and then it will try to POST if there are no errors.
+
+h5. valid?
+
+Runs all the local validations and will return true if no errors.