mca blog

i keep looking for ways to help people 'get' REST. not URLs or HTTP Methods; but REST itself - in a nutshell. so here's a new angle i've started playing with: "REST Upside Down." in this explaination, the usual litany of REST constraints are presented in what is commonly thought of as 'reverse' order. i find it helps people focus on the most important item first - hyperlinks.

Use Hyperlinks to control the workflow

When you send a requested document to the client, include hyperlinks that can advance the workflow (or state) of the application. Are you sending a list of customers to user? If yes, consider including the link to add a new customer, edit or delete any of the ones in the list, and possibly filter the list using a query pattern. If you are not sending hyperlinks for workflow, you are not building a REST-ful implementation.

Let the client select the representation format of the request

When you code your server responses, don't force the client to accept only one serialization format (XHTML, JSON, XML, etc.). Let the client tell your server which format it should recieve. If the client doesn't tell you, send the 'default' format (usually XHTML). You can tell what format the client wants by checking the Accept header on each request. This will usually contain one or more MIME-Types. You can tell the client the MIME-type of the reply by setting the Content-Type header in the response.

Make all your server interactions stateless and, where possible, cacheable.

In order to support large-scale, widley distributed use of your application, make all server interactions stateless. Don't require the client or server to 'remember' any information between requests. Don't 'hide' key information about the message in the body of the response. Instead, take advantage of HTTP Headers to ship meta-data about the body of the message between client and server.

In order to improve the usability and scalability of your application, use the full range of the standard HTTP Methods.

Most application operations involve retrieving information from a server (HTTP GET). However, when appropriate, clients should be allowed to define new resources (HTTP POST), update existing resources (HTTP PUT), and delete existing resources (HTTP DELETE). clients should also be allowed to validate the existence of resources (HTTP HEAD) and check on the allowed operations for a resource (HTTP OPTIONS). Misusing these methods and/or inventing new methods degrades a client's ability to understand and use your application.

Use URIs to identify resources, not actions. The list of possible URIs is the only infinite commodity you have.

URIs (or URLs, if you prefer) are 'pointer's that can be de-referenced by a server into a representation of information and returned to a client upon request. There are only a few rules on how to construct a URI. Since a URI need not be tied to a physical file or directory, you can use URIs to identify any stateless message you wish to send to a client (/user/mike, /weather/today/, etc.). Also, URIs are 'names', not 'actions.' For example, /user/add/?name=mike is not a well-formed URI.