Since its inception, Ruby on Rails (RoR) has been at the forefront of RESTful Web Service development.  And ActiveResource, the RoR answer to the client-side of RESTful web service interaction, is an invaluable tool for integrating your RoR application with the many services that may be available to you.

ActiveResource can take RESTful resources and map them to client-side classes with almost no configuration or code required by the application developer.  Lets take a look at the classic “Person” service example:

class Person < ActiveResource::Base
  self.site = “http://www.bti360.com/person-service”
end

In these few lines of code we’ve created a Person model class that can be used throughout our application much like our ActiveRecord based model classes that interact with our database.  What can we do with this class?  Well, out of the box you can do all the standard CRUD operations.

Lets take a look at how some of these operations might look.

So say we want to create a new person.  Here is some sample code to do just that:

jp = Person.new(:first_name => 'Jon’, :last_name => ‘Pierce’)
jp.save # sends POST /people/ (create)

The save method above will send the following XML to the service in the POST request body:

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <first-name>Jon</first-name>
  <last-name>Pierce</last-name>
</person>

And any response body from the request will be parsed and assumed to be the saved representation of the new person.  Once the person has been saved we can easily make updates:

jp.new? # => false
jp.last_name = ‘Awesome’
jp.save # sends PUT /people/1 (update)

So we’re following standard convention here to get us moving very quickly.  Similarly we could delete our new person:

jp.destroy # sends DELETE /people/1 (delete)

And now JP is gone.

The final piece to the CRUD puzzle is the ‘find’ method.  As with the others, this method behaves similarly to the ActiveRecord find method.  Here are some examples:

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

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

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

As you can see ActiveResource provides a lot of power into very little code for the application developer, and this blog has only scratched the surface.  ActiveResource has many more options and features to allow you to taylor it to your specific needs and purposes, including validation, error handling and many others.

I would recommend diving into the ActiveResource API documentation on the RoR homepage if you’re interested in learning more about it.  Or feel free to shoot me an email, I’d love to discuss it with you.

Happy coding!!!

In this blog we are going to take a look at clients of RESTful Web Services. RESTful Web Service clients are programs or libraries that can be used to consume RESTful Web Services. These clients are responsible for making the underlying HTTP requests to a RESTful Web Service. Every modern programming language has one or more libraries for making HTTP requests and each client will usually use one of these libraries.

To build a RESTful Web Service client you will need an HTTP library with at least these features:

• Supports GET, POST, PUT, and DELETE requests: These four http methods are required when creating and modifying resources.
• Supports adding and modifying request headers: Specific request header values need to be used to specify the representation of the resource (json, xml, jpg, etc).
• Allows the programmer to customize the data sent as the entity-body of a PUT or POST request: This means that the programmer can include any data they want in any representation they choose as the body of the request.
• Allows the programmer access to the response code and headers: The programmer needs access to the response code to determine if the request was processed successfully or if any error conditions exist. Access to the header is used to determine the representation of the resource in the response body.
• Supports HTTPS and SSL certificate validation: This ties in with security as many RESTful Web Services and http servers in general will require the client to support secure communication.

Example Libraries

Some example libraries that support these features are as follows:

• Java: Spring's Rest Template, Apache HttpClient
• Ruby: ActiveResource
• Javascript: Many solutions (XMLHttpRequest, ExtJs, jQuery, Dojo, Prototype, etc)
• C++: Curl
• .NET: HttpWebRequest and HttpWebResponse

Once you have an acceptable HTTP library, you will need another library or piece of code to convert your resource into the chosen representation and vice-versa. The most common representations currently used in RESTful Web Services are XML and JSON.

In our next blog post we will take a closer look at some of the libraries programmers use in their RESTful Web Service clients and dig into some examples.

Here's a quick look at how to get your RESTful web service off the ground fast using the Ruby on Rails Framework.