The REST Architectural Pattern

What is REST?

Roy Fielding in his 2000 doctoral dissertation defined the REST architecture style, which stands for REpresentational State Transfer.

"REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes." - section 5.2.1.2.

REST is a land of nouns - the verbs are out of sight. Like in H.G. Wells' The Time Machine where the beautiful Eloi live on the surface without a care in their pretty little heads, and the Morlocks live underground doing all the gritty work. So it is with REST; we see the Eloi (the nouns) but the Morlocks (the verbs, GET, PUT, POST, ...) do the work.

Five and a Half Constraints

Roy defined constraints to make the use of a service easier, more reliable, and more scalable.

  1. Client-Server

    Separation of concerns is the reason behind this constraint; components can evolve independently.

  2. Stateless

    Only the client contains state and the client must resend all state for each request. Scalability is improved since the server does not have to store the state, but at the cost of increased communication.

  3. Cache

    Items may be marked as "cacheable" to save resources.

  4. Uniform Interface

    The interface is standard across all interactions making it easier to understand, but less efficient. " ... hypermedia as the engine of application state."

    Four Sub-Constraints

    1. Identification of resources through a URI

      A resource is not the representation. A resource may be database data, but it is represented by JSON or XML.

    2. Manipulation of resource through representations

      Enough information like id and properties needs to be sent.

    3. Self-descriptive message
    4. Hypermedia as the Engine of Application State (HATEOAS)
  5. Layered System

    This constraint simplifies interactions since a client can be connected directly to the server, a load-balancer, or a cache provider.

  6. Code on Demand (optional)

    Code like JavaScript can be downloaded and run on the client.

Distributed Hypermedia Options

  1. Create an image of the data and send it to the browser.
  2. Send the data and a bit of code to render the data.
  3. Send the data and specify the data type and let the user select a rendering engine.

HTTP Verbs

  1. GET

    Reads a resource. GET is idempotent, it can be called once or a hundred times and it does not change the resource directly (it may change a counter or ancillary data, but not the resource). Example: http://example.com/employees/345123

  2. POST

    Creates a new resource and gives it an id plus any miscellaneous operations needed.
    Example: create a new performance_review for employee 345123 http://example.com/employees/345123/performance_review

    After creating an object whose id was created by the server, the developer should return a link to a new object in the Location header.

  3. PUT

    Replaces the contents of an entire resource by using an identifier. PUT may be used to create a specific resource if the client already knows the identifier for the resource. If creating an object with PUT, the Location header does not need to be set since the client already knows it.
    Example: http://example.com/employees/345123

  4. PATCH

    Similar to PUT, but only updates a part of a resource by using an identifier. Can be done by sending some fields, or by sending a JSON patch document with a list of commands and values.

  5. DELETE

    Removes or deletes a resource known by its identifier.
    Example: http://example.com/employees/345123

  6. OPTIONS

    Retrieves the options of a resource.

  7. HEAD

    Only retrieves the HTTP headers of a resource.

Return formats

The most common return type of objects now is JSON (specified in the headers as "Content-Type: application/JSON"), although some systems will use XML. The HTTP request can set the "Accept" header to specify what output is desired.

Response Codes

Use the appropriate HTTP response codes.

Status CodeKeywordDescription
200 OK Everything is fine. Here is some content.
201 CREATED Everything is fine, something was created.
204 NO CONTENT Everything is fine, but nothing is in the response body. This is common after a successful DELETE operation.
304 NOT MODIFIED A "If-None-Match: [ETag]" was sent by the client and the server decided the requested object has not changed. The server does not need to send the response again and the client can use its cached copy.
400 BAD REQUEST The server didn't like the format of the request.
401 UNAUTHORIZED Missing or bad authentication, I don't know who you are.
403 FORBIDDEN I know who you are but you don't have permission for this operation.
404 NOT FOUND The requested resource is missing.
405 METHOD NOT ALLOWED The requested resource exists, but the HTTP verb is not valid.
412 PRECONDITION FAILED Most commonly returned when the client is trying to PATCH or PUT a resource that has been modified since the last encounter.
500 INTERNAL SERVER ERROR Something bad has happened unexpectedly on the server.

 

Tips on Good Resource Names

  1. Include data in the URL, not the query string. api/films/videos/12345 not /films?type=videos&id=12345

  2. Make the URL segments lower-case with words separated by "_"

  3. Use plural nouns for resources names, api/employees/107

Examples of REST services:

  1. https://graph.facebook.com/youtube?fields=id,name,likes
  2. maps.googleapis.com/maps/api/geocode/json?address=austin&sensor=false
  3. http://instagram.com/developer
  4. ProgrammableWeb.com
  5. https://developer.github.com/v3/git/refs/
  6. https://developer.atlassian.com/jiradev/api-reference/jira-rest-apis
  7. https://dev.twitter.com/docs/api
  8. http://developers.facebook.com/docs/reference/api/
  9. https://developer.linkedin.com/apis