An overview of REST

REST is maybe the most wrongly used word within the web world. It has became synonym with any sort of API that can be used of HTTP. As this frustrates me sometimes I will try to explain what REST is about and it is very simple and elegant in the basis.

REST stands for Representational State Transfer and is an architectural style to connect multiple components with each other. It defines some constraints to which a RESTful api should adhere. The constraints will be explained below:

Resources

A resource is the most abstract thing used in REST. A resource can be any piece of information with different represenational forms. Every resource is identified by it’s Uniform Resource Identifier (URI). For example; http://example.com/persons/1234 can be the resource of the person with id 1234 and http://example.com/persons/1234/orders can be a list with orders of this person. Depending on the Accept header the representation can differ.

Verbs

On every resource some kind of action can be performed. Every resource can have different methods and not all methods have to be supported. The define the type of action that can be performed a verb is used. Below are some verbs that are commonly used:

  • GET; The most known and probably the most used method. Retrieve the current state of the resource in a representation
  • POST; Update the current state of the resource with a new state.
  • PUT; Create a new resource on a specified URI.
  • DELETE; Remove the resource.
  • HEAD; Only retrieve the metadata. Useful to determine is the local cached copy is expired.
  • And more, there are a lot more extra/proprietary verbs in use now. For example WebDAV uses PROPFIND, COPY, etc

Status codes

The server always responds with a status code indicating what type of message is following and how the client should proceed. I’ve listed the most used but you can find the full list in the RFC2616.

  • 200; OK
  • 301; Resource moved to another location. The client should proceed to the new location and forget the previous location.
  • 401; Forbidden to access the resource
  • 404; Resource not found
  • 500; Internal server error

For example, when a 301 is received the server sends another header Location: /newresource to redirect the client to that location an try to retrieve the resource from there.

Representation

Every resource has it’s own representation. A Person can be represented with XML or JSON and still contains all information about the Person, only the representation is different. An image can also be shown in different formats for example JPG and PNG and still be the same image.

A person represented in XML could look as follows


  John Doe

The same person in JSON will look like this.

{
  type: "person",
  name: "John Doe" 
}

Both contain the same information and only the format is different. When a new media format is developed this can be added without breaking backwards compatibility by adding a new handler for this format.

Hypermedia

Known from the hyperlink, hypermedia has a special role within REST. With hypermedia it is possible for resources to link to each other and tell the receiving client what the next resource should be or where to find other interesting resources.

For example when we retrieve the resource /person/1234 the resource can contain some link tags with additional resources. The client can search for a link with rel=”avatar” and follow this link without knowing the URL on forehand.


   John
   
   

Examples

Two examples to clarify REST and how it is used in real life.

PUT

When we want to create a new resource we execute a PUT command.

PUT /person


    John Doe

The server responds with the following header

HTTP/1.1 201 Created
Content-Type: text/xml
Location: http://example.com/person/1234


    1234
    John Doe

The server responds with a 201 which means the resource is created and available on the given URI. Also the resource itself is returned in the body. When the server responds with an 204 the body is not returned.

GET

When we follow the link contained in the header Location: http://example.com/person/1234 we peform a GET on the URI:

GET /person/1234

The server responds with the resource

HTTP/1.1 200 OK
Content-Type: text/xml


    1234
    John Doe

Summary

When an API adheres to the constraints above it can be called a RESTful API, it should support more than only the simple GET and POST most API’s do. Also the resource should play a central role and the API should not be used as some sort of RPC. Following these constraints can create very simple and elegant API’s. In a follow up post I will try to explain what makes a good REST url and why.