REST - Taking a Closer Look (Part 7)

We are going to take a little detour and look at the method values available.  These values have very defined intentions for use and how they should be treated on the response side of the transaction.  The w3.org has documented eight different methods in the HTTP v1.1 specification.

• OPTIONS
• GET
• HEAD
• POST
• PUT
• DELETE
• TRACE
• CONNECT

It seems that all communication is now expected to work through the GET and POST methods.  The GET is intended for retrieving data with potential for cache.  The POST is intended to push data onto the server.  These two methods are very common and do not require a lot of discussion.

OPTIONS Method

The OPTIONS method intends to determine what options are available to the client.  This may be useful in the cases of determining a user has access to specific resources on the server.  The w3.org HTTP v1.1 specification has this to say about OPTIONS.

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

Responses to this method are not cacheable.

In the Book example I have been working through, I could it being used to determine if a user has read-only access or may have create, update and delete privileges as well.  The client application could be formed in a way to respect the response of an OPTIONS request to provide certain features to the user based on their authorizations.

HEAD Method

HEAD, is header that I have only read about and never use in practice.  The definition as defined by w3.org from the HTTP v1.1 specification is,

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification.

Two things come to mind.  Checking the end point is valid and exists, pushing data to the server without sending a response to the client.  Now these two are likely very useful in certain conditions.

My extinct is to avoid HEAD whenever the User's experience is at stake.  Another words, if there is a need to make a request to the server to gather information.  It does not seem practical or feasible to make a HEAD request first to determine if the end point is valid and contains fresher data than the browser's cache.  The result would be in certain situations an additional request to retrieve the data.

I can see this being used in a CDN type implementation, where the delivery nodes are responsible for checking for updates periodically.  In this instance that User is waiting for the response and additional requests.  The node can make requests more often to check staleness using HEAD and then make a GET request to retrieve an update when necessary.

Another useful condition may be to push user activity information to the server.  In this case, the response codes should indicate whether the user is still allowed to access the system.  Otherwise, if the system is dependent on the client pushing data or communicating on a regular basis to avoid a session disruption from the server side.

PUT and DELETE Methods

The PUT and DELETE methods are primarily used in RESTful services.  They are used to indicate the action of updating or deleting some data.  I have already worked through the PUT and DELETE methods in a previous post.  Check it out for what I have discovered there

TRACE Method

TRACE is a method intended for testing and debugging purposes.  The method indicates that the server should do nothing more than reflect the request data back to the client.  HTTP v1.1 identifies this as,

The TRACE method is used to invoke a remote, application-layer loop- back of the request message. The final recipient of the request SHOULD reflect the message received back to the client as the entity-body of a 200 (OK) response. The final recipient is either the origin server or the first proxy or gateway to receive a Max-Forwards value of zero (0) in the request (see section 14.31). A TRACE request MUST NOT include an entity.

This is useful to identify how a request may be processed on the way through all of the various hops between the client application and the server.  If there are no hops between the client and server there is likely going to very little change of the request on the way through to the server.  I have never used this in practice, but I am intrigued to learn more about it and how I may be able to utilize it.

CONNECT Method

This method appears to be reserved but not implemented.  So there is not much to say about it, except it may be used with SSL tunneling.  See the w3.org's HTTP v1.1 specification for more details and updates to the specification.

REST - Taking a Closer Look (Part 2)

First goal is understanding the request model as stated in my previous post REST - Taking a Closer Look (Part 1).  For this portion of the exercise, I will start take a closer look at the Book implementation.

The book model is simple concept and one that we would recognize from our daily lives.  A book has basic properties,

• title
• description
• author
• ISBN

What is REST?  REST is representational state transfer (see Wikipedia for more details).  More or less, it's a software architecture by which we transfer state from one place to another.  In terms of the web, transferring state of resources from the client (browser) to the server (web server->database).  I strongly suggest reading the Wikipedia entry, as it has some very useful and important details on implementation and separation of concerns.

REST sets out to model the concept of CRUD operations (Create, Read, Update, Delete).  It mimics these operations by using POST to Create, GET to Read, PUT to Update, DELETE to, well, Delete. 

With a simple understanding of REST, let's look a little closer at a Book implementation.  Initially, you'll want to see a list of books that are available.  We would model a URL using the guidance of REST like this.

GET http://localhost:8080/research-grails-rest/book/list

This URL has no unique pieces to it.  The resource is defined by book and the operation is defined by list. As a result, all defined knowledge of the representation of a book will be listed.  We can say this about any resource that is available in the system that provides an authorized list operation.  Within the context of the Grails application, all of the work is done on the server and returned in an HTML page.  However, in an Ajax based client, the list operation would return all of the data as a data structure and decouple the operation from the client view.

Screenshot: Result of book/list.

As a part of the architecture, the GET request could be marked as cacheable.  In other words, the browser could use a copy of this data from it's local cache rather than making a request to the server.  The resource, book, would have to mark the list operation as cacheable and provide a timeframe in which that cached data is considered fresh.  Once that cache entry is considered stale by the browser or by revalidation by the server, a new version of the resource will be made available to the end user.

For a simple operation like, GET, this about the extent of it.  In the next post, I will discuss the POST method (Create).