Last updated September 20, 2021

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.

Client-Server
Separation of concerns is the reason behind this constraint; components can evolve independently.
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.
Cache
Items may be marked as "cacheable" to save resources.
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)
Layered System
This constraint simplifies interactions since a client can be connected directly to the server, a load-balancer, or a cache provider.
Code on Demand (optional)
Code like JavaScript can be downloaded and run on the client.

Distributed Hypermedia Options

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

HTTP Verbs

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
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.
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
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.
DELETE
Removes or deletes a resource known by its identifier.
Example: http://example.com/employees/345123
OPTIONS
Retrieves the options of a resource.
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 Code	Keyword	Description
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

Include data in the URL, not the query string. api/films/videos/12345 not /films?type=videos&id=12345
Make the URL segments lower-case with words separated by "_"
Use plural nouns for resources names, api/employees/107

Examples of REST services:

The REST Architectural Pattern