Lecture 30: Support for REST in Rails 1.2

Agenda

Revisit Duncan Cragg's views on REST
Rails 1.2 Support for REST

Duncan Cragg Revisted

STREST: Service-Trampled REST
The Problem: Using HTTP to carry function calls rather than resources
Breaking the GETable Web
- If you use the Web to carry functions, you tend not to give your resources URLs. Instead, you access a single URL and supply internal ids that are hidden from the end-user
- This tends to break the nice properties that Web resources have of being cacheable, indexable, and linkable.
- Plus, a lot of software already understands the URIs and the semantics of GET. If your resources are available at individual URIs, a broader range of software can ACCESS your information
- Furthermore, each response to a GET comes with a Content-Type header that tells the software what type of resource is being returned. If your application makes use of standard resource types, then a broader range of software can PROCESS your information and these resources may contain additional URIs that allow clients to access related information
  - This approach is opposite to that of SOA and SOAP which recommends creating custom WSDL files and custom XML schemas for your service
  - Such an approach leads to only a small number of clients that can process the information provided by your service
- Another problem is that some services allow GET requests to change the state of the server; this breaks the idempotent nature of GET and reduces the utility of the overall service: links should be followable by programs, engines, bots and people without fear of side-effects. It's a basic, fundamental expectation that is weaved into every strand of the Web
Breaking the POSTable Web
- Cragg claims that the use of POST to handle state-changing function calls comes with two costs: scalability and interoperability
- With respect to scalability, the function call is a bottleneck over the resources being changed, especially when resources are hidden behind a single URL; there is no way to update two resources in parallel under such a scheme and the only way write operations can scale is by allowing them to occur in parallel
- Cragg states that functions are expensive and don't proliferate while URLs for individual resources are cheap and do; if you have multiple URLs for your resources, you can enable parallel updates since two POSTs can occur at the same time to two separate URLs. You can achieve greater scalability by splitting your resources across multiple machines simply by varying the URIs that point to your resources
- With respect to interoperability, Cragg claims that the Web displays high interoperability: in particular the Web is built around a small number of resource types that most clients (i.e. browsers) understand. Non-standard content can still be downloaded, even if the general purpose client can't handle it; but for the most part standard types are used so that the users of a website can access most of its functionality via their browsers
- In contrast, if the Web is used to carry function calls, the data being passed around is defined by a single provider and can only be handled by the single implementation of that Web service. Cragg argues that standardizing on resource types and the interaction around these types (such as the conventions that govern Web-based forms) provides more interoperability than a function call approach can ever hope to achieve
The STREST piece ends with Cragg urging that people who implement Web 2.0 web services should abandon STREST and switch to REST saying: It'd be a shame for Web 2.0 to become detached from the linkable, bookmarkable, indexable, cacheable, parallelisable and interoperable Web 1.0 that we've all built.

Support for REST in Web 2.0

This past summer at RailsConf 2006, the creator of Ruby on Rails, David Heinemeier Hansson, gave a keynote address outlining some of the ways that the next version of Rails, Rails 1.2, supports REST.
Some background: Rails is an example of a framework that enforces convention; if you follow the conventions (essentially codified best practices), you get a lot of power for “free”;
With Rails 1.2, the Rails team has added new conventions that, if followed, produce Web applications that follow the REST architectural style
Some additional background: Rails follows the Model-View-Controller pattern and the focus of the changes to Rails 1.2 is the controller.

Rails Controllers

A Rails controller is in charge of receiving a request from a browser, doing something with it (perhaps by updating the model) and then indicating what view needs to be displayed to the user as a result
As functionality is added to a Rails application, methods tend to get added to controllers to provide a “home” for that functionality. DHH admits to having, in the past, controllers with 10-15 methods each
Following Rails 1.2 conventions, controllers switch to having 4 primary operations: CRUD (create read update destroy)
Furthermore, controllers become associated with a particular resource to which the CRUD operations are applied

Rails URLs

In the past, a typical Rails application might have had URLs that looked like this:

POST /people/create 
GET  /people/show/1 
POST /people/update/1 
POST /people/destroy/1

Such URLs violate the DRY principle, i.e., Don't Repeat Yourself

In REST, the URLs become

POST   /people 
GET    /people/1 
PUT    /people/1 
DELETE /people/1

NOTE, DHH maps CRUD operations to HTTP like this:

CREATE	READ	UPDATE	DESTROY
POST	GET	PUT	DELETE

Unfortunately, standard HTML and Web browsers do not allow the use of PUT and DELETE in HTML Forms. As a result Rails 1.2 makes use of GET and POST, and when it needs to do a PUT or a DELETE, it adds a hidden field to the POST request to indicate the desired semantics. If, in the future, the support of PUT and DELETE becomes widespread, then Rails can switch to using the actual HTTP methods instead.

Now, the way in which the standard CRUD operations get mapped into a Rails 1.2 controller is like this:

class PeopleController < ActionController::Base
    # GET /people
    def index() end
    
    # GET /people;new
    def new() end
    
    # POST /people
    def create() end
    
    # GET /people/1
    def show() end
    
    # GET /people/1;edit
    def edit() end
    
    # PUT /people/1
    def update() end
    
    # DELETE /people/1
    def destroy() end
end

The design goal here was to have the first part of the URL always reference a resource. If special semantics are required when accessing the resource using a particular method, then a semicolon is added, and a keyword is placed after the semicolon. So in the case of needing to an edit a resource, you tack on ";edit" to a resource when getting it. In the case of creating a new object with default values for its attributes, you tack on ";new" to the URL when getting it.

CRUD is not a goal…

In his keynote, DHH states CRUD is not a goal, it's an aspiration, a design technique
In particular, he makes the claim that if you find yourself adding a non-CRUD operation to a controller that suggests that you have not completely modeled your domain... i.e. there is a resource out there that has not yet been made explicit

He expands on this with the following example:

class Group < ActiveRecord::Base
    has_and_belongs_to_many :users
end

class User < ActiveRecord::Base
    has_and_belongs_to_many :groups
end

class UsersController < ActionController::Base
    # POST /users/1;join_group?group_id=2
    def join_group() end
    
    # POST /users/1;leave_group?group_id=2
    def leave_group() end
end

In this situation, we have two resources users and groups with a many-to-many relationship between them. When updating a user, you may want to have them join a particular group or leave a particular group. You can use the semicolon trick to help in this regard but it doesn't feel right.

DHH points out that what you want to modify in this case is NOT user but a new resource that exists between users and groups, a relationship called membership

class Group < ActiveRecord::Base
    has_many :memberships
    has_many :users, :through => :memberships
end

class User < ActiveRecord::Base
    has_many :memberships
    has_many :groups, :through => :memberships
end

class Membership < ActiveRecord::Base
    belongs_to :group
    belongs_to :user
end

class MembershipsController < ActionController::Base
    # POST /memberships?group_id=1&user_id=2
    def create() end
    
    # DELETE /memberships/3
    def destroy() end
end

In this new implementation, you have a Membership class and when you update a membership between a user and a group, you perform CRUD operations on a Membership resource

Other REST features in Rails 1.2

Responding to MIME types
- Rails provides a respond_to method that allows you to query the incoming request to determine how the resource should be formated (i.e. what representation of the resource is desired)
- If the client doesn't specify, they get HTML, but if the ask for XML, they get XML; Rails 1.2 provides mechanisms for allowing you to specify custom mime-types and then hooking into the respond_to method to generate a resource in the custom mime-type on demand
ActiveResource
- A client-side library for consuming the REST based services being offered by the server-side controllers
- You deal with Ruby objects, creating, updating, destroying, etc. and ActiveResource transparently converts your object into XML and invokes the correct HTTP method on the correct URI
- It appears that this library may have been pulled from the final release of 1.2 (it was present in versions before the release candidate that was made available at the end of November.)

Web Services