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 126.96.36.199.
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.
Separation of concerns is the reason behind this constraint; components can evolve independently.
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.
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
- 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.
- Manipulation of resource through representations
- Self-descriptive message
- Hypermedia as the Engine of Application State (HATEOAS)
Enough information like id and properties needs to be sent.
- Identification of resources through a URI
- 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)
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.
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
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.
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.
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.
Removes or deletes a resource known by its identifier.
Retrieves the options of a resource.
Only retrieves the HTTP headers of a resource.
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.
Use the appropriate HTTP response codes.
|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: