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 6)

In my last post, I talked a bit more about the PUT and DELETE methods of a request.  I raised a concern regarding the Grails and it's support for PUT and DELETE due to my inabilities to make a PUT request from a form.  After further investigation, I found a reference in the HTML5 changelogs posted on June 24, 2010 indicating that PUT and DELETE methods were removed from the specification.

As expected, the following code works without any issues.

jQuery.ajax({ url: "http://localhost:8080/research-grails-rest/book/delete/2", type: "DELETE" });

This further proves the point that only the form submission using these methods are affected.  This restriction may not be an issue for applications that are primarily Ajax driven.  However, I have read in several API docs now something similar to this from the jQuery Ajax documentation.

"The type of request to make ("POST" or "GET"), default is "GET". Note: Other HTTP request methods, such as PUT and DELETE, can also be used here, but they are not supported by all browsers."

The trend in several stackoverflow articles is a POST tunneling concept.  Essentially, instead of using the PUT or DELETE methods, send everything over POST.  Then specify through a hidden form input or HTTP header the correct method.  This resolves the problem for form submissions and lack of browser support.

With that resolved, it is time to look closer at more complex structures.  My next post will be centered around understanding how the state of a collection of books is transferred.  After that investigating how to perform operations against that collection.

Citations from stackoverflow.com regarding POST tunneling:

• Are the PUT, DELETE, HEAD, etc methods available in most web browsers?
• Is there any reason not to use HTTP PUT and DELETE in a web application?

REST - Taking a Closer Look (Part 5)

In this post, we'll take a closer look at the update process using PUT with the Grails project.   REST defines updates as a HTTP PUT method.

First we need to make a few adjustments to the code to make the update operation respond to the PUT method and alter the edit form to ensure it is sending in a method of PUT.

Alter the allowedMethods array to recognize PUT for the update method.

Alter the form method to ensure it sends PUT as the method.

Now that we have ensured the method is set to PUT on the form and the controller will accept PUT as the method from the client let's test.  (After selecting a specific book, click the Edit button along the bottom of the view.)  Altering some data and clicking the Update button we should be in business to see the transaction.  The following screenshot details the HTTP headers transferred during the state transition.

Here we can see that the request was actually done using POST.  Internally within the request parameters a PUT method is specified.  This is detailed further in the Grails 2.0.0 documentation.

Issuing a request with a method other than GET or POST from a regular browser is not possible without some help from Grails.

This doesn't seem to be consistent with the REST architecture or the HTTP v1.1 specification.  Grails is also blocking a method of PUT coming from the browser with a 405 - Method Not Allowed response.  Requests made with cUrl go through without error.

$ curl --request PUT http://localhost:8080/research-grails-rest/book/update/1 --verbose
* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> PUT /research-grails-rest/book/update/1 HTTP/1.1
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 302 Moved Temporarily
< Server: Apache-Coyote/1.1
< Set-Cookie: JSESSIONID=F91DEA3433A1F745B249C0F7E3E9988E; Path=/research-grails-rest/; HttpOnly
< Location: http://localhost:8080/research-grails-rest/book/show/1
< Content-Length: 0
< Date: Tue, 24 Jan 2012 10:45:05 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0

The response location,  http://localhost:8080/research-grails-rest/book/show/1, indicates the controller received the request correctly and performed the update.

What am I trying to get at?  One concern I have is support by most/all browsers for the HTTP v1.1 specification.  Another concern is around the heavy handiness around the method support on Grails part.  I concede I am now Grails expert and there may be a very simple solution to this.  I haven't found it yet if there is.  Furthermore, quick check of delete operation from the browser blocks the DELTE method even after altering the allowedMethods.

So what have we learned?  The PUT and DELETE methods have special considerations when involving the Grails built views.  It may be worth approaching another framework to interact with the REST services provided.  However, the controller has tightly integrated the responses on each call with the next view.  I think this is intended due to the nature of Grails application development.