REST

Everyone wants to make a RESTful web service these days. But REST is much more than naming resources with nouns and just not doing SOAP.

Definition

REST, or Representational State Transfer, is an architectural style for distributed systems defining certain constraints that provide efficiency, scalabilty, and other desirable attributes.

REST was introduced by Roy Fielding. The constraints he identified were:

REST is an architectural style, NOT a product, NOT an API.

The World Wide Web is an example of a RESTful system.

Principles of REST

A RESTful system is characterized by

Writing RESTful Web Services

Thinking RESTfully

RESTful and non-RESTful URIs

RESTful
  http://ctysr.ch/profiles
  http://ctysr.ch/profiles?what=pizza&where=90069&page=4&rpp=20
  http://ctysr.ch/profiles/2734
  http://ctysr.ch//twitter-handles/jp
  http://ctysr.ch/providers/2345/budgets/4567
Non-RESTful
  http://example.com/order-system?op=deleteCustomer&id=2
  http://example.com/find-events?where=90069&after=2010-05-20
  http://example.com/api/products/update?id=3&name=mouse

Use a framework

If you are writing a webapp back-end, you most certainly are using some kind of server-side product like Node for JavaScript, Django or Twisted for Python, Spring for Java, Rails for Ruby, a .NET backend, or plain old PHP. Many of these products have a mechanism for "doing REST". For Java, you can use a JAX-RS implementation such as Jersey, RestEasy, or CXF.

REST and HTTP

HTTP is a stateless request-response protocol

TODO IMAGE

Using HTTP Methods RESTfully

RequestMeaning
GET /thingsGet all things. Use query parameters to restrict set or paginate.
PUT /thingsReplace the set of all things. Put set in payload.
POST /thingsCreate a new thing. Server sets id. Put representation of new thing in payload.
DELETE /thingsDelete all of the things.
GET /things/8Get thing 8.
PUT /things/8Replace thing 8 with new thing, but id stays 8. Put representation in payload. Or create a new thing with id 8.
POST /things/8If thing 8 is a collection, create a new item in this collection with server generated id.
DELETE /things/8Delete thing 8.

You can implement OPTIONS yourself, too. HEAD will pretty much be handled by a framework.

Respect method constraints:

HTTP Request Headers

There are many request headers but the one you might use most frequently is the Accept header. To request that the server give you a representation in a desired format, supply a header such as:

HTTP Responses

Use response codes as they were intended to be used. The ones you should be aware of (that is, that you may set yourself as part of your application) are:

CodeMeaning
400Bad Request
401Authorization Required
403Forbidden
404Not Found
405Method Not Allowed (service doesn't support the requested method at that URI)
406Not Acceptable (server can't give back a representation in a requested format)
415Unsupported Media Type (server can't process the request body)
200OK
201Created (usually you should set the Location header for this)
202Accepted (used for asynch requests)
204No Content
301Moved Permanently
409Conflict
410Gone

HTTP Response Headers

You will probably set Location and X-Version yourself. A framework will do the others.

Links