SubSift REST API: HTTP Request Methods

HTTP Request Methods

When you enter a url into a web browser the browser performs an HTTP GET request to the url. This usually returns a web page in the form of an HTTP response which the browser displays. However, GET is only one of several HTTP request methods; the five that are most significant for REST web services are: GET, HEAD, POST, PUT, DELETE. Of these, the most familiar to HTML authors are GET and POST - as used in hyperlinks (e.g. <a href="http://www.example.com">...</a>) and web forms (e.g. <form method="POST">...</form>); the other three methods are less well known but have recently become more widely known due to the popularity of REST web services. An important convention of the REST protocol is that different HTTP request methods when applied to the same url will produce different actions. For example,

GET http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc

will retrieve a representation of the pc bookmarks folder belonging to user kdd09, whereas

DELETE http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc

will delete that same representation.

Further details of HTTP request methods are described in a W3C document on RFC 2616 and in the less readable standards document RFC 2616, Fielding, et al (1995). A starting point for finding out more about REST is this Wikipedia article.

Supported HTTP Methods

The SubSift REST API uses the following HTTP request methods in the conventional way as follows:

GET For "show" and "list" methods. These methods do not change any data.
HEAD For "exists" methods. These methods check for the existence of a data item. They return a status code in the response header but do not return any data in the response body.
POST For "create" and compute methods. These methods change data.
PUT For "update" and recompute methods. These methods change data.
DELETE For "destroy" methods. These methods change data.

Faking HTTP Methods

Not all client software supports all of the required HTTP request methods for communicating with a REST API (for example, some browser plug-ins such as Flash, only support GET and POST). Without the HEAD, PUT, DELETE only a subset of the features of a REST API would be available to such clients. For this reason it is common practice for a REST API to offer a way of overriding or faking the real HTTP method so that the API behaves as if a completely different method were used - for instance, treating a POST as if it were a DELETE or some other method. One technique for achieving this behaviour is to support an HTTP override parameter. SubSift does exactly this using the _method parameter which is available across the entire API.

When communicating with the SubSift REST API, clients that can not issue certain requests methods can use one of the universally available methods GET or POST with the added parameter _method to fake the required method.

HEAD If HEAD is not supported, use GET with parameter _method=HEAD
PUT If PUT is not supported, use POST with parameter _method=PUT
DELETE If DELETE is not supported, use POST with parameter _method=DELETE

For example, in the SubSift REST API, the following GET behaves as is if an HTTP HEAD method had been used.

GET http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks/pc?_method=HEAD

Note that the _method value is case insensitive and so _method=HEAD behaves the same as _method=head