How I explained REST to my rubber duck (2/2)
A simple and inexact rough explanation of REST
How I explained REST to my rubber duck (1/2) - Synopsis
Some principles of REST
Representation - The information transferred to and from the server is not necessarily stored on the server in the form it is transmitted. It is the
representation of the information that is transferred. For example: a web page you view on your browser (-the client) was received from a server in the form of an html page. The server, however, might have created that html from various parts that might include information stored on a database, master pages, etc. This is where REST gets its name from - Representational State Transfer - the server and client transfer to one another a representation of their information (their "state"), not the information itself that is (or is to be) stored.
The interaction between the server and client is by simple actions that the client can request and that the server can respond to. The client can ask to GET information from a url. Or it can request to alter the state of information of a url on the server. This alteration can be to POST new information to a new url; PUT updated information in a url instead of old information; and DELETE information from a url.
Idempotence - After a PUT, DELETE, or GET request, subsequent identical requests should not further alter the information on the server. E.g. After a 'DELETE url123' request, subsequent requests to 'DELETE url123' should not delete any more information from the server. (POST
should add information every time it is called. It is not
supposed to be idempotent.)
All information is identified by an identifier (nominally a url). And, as mentioned earlier - when requesting a url - the information transferred will only be a
representation of the information identified by that url.
Another type of information that needs to be known by both the server and the client (besides the entry points for the service) is the possible types of representation - MIME types. For example: a client must know how to interpret an html page.
HATEOAS - Hypermedia As The Engine of Application State - The possible urls that the client can use next are expressed in a server's response as hypermedia - media items that are associated with urls. Text links (-hyperlinks) are a common type used.
HATEOAS is a fundamental principle of REST.
Code On Demand - A server may make available code that the client can execute. For example, a web page you view can execute JavaScript code which was received from the server.
There should be a distinction between a server and client. When the service is used - one party should be in the role of the server, and the other - the client.
Statelessness - A server must not store the 'state' of a session such as some information being left by the client and referred to in a subsequent action
when that information is only correct during the first action's session. (The client can, of course, post information which might be used at a later date as well.) If the concept of a session is required - all information needed should be stored on the client and sent with every request. For example: if a person is filling a shopping cart on a web site - the state of the cart should be stored on the client only. Every time the server's action is needed on that cart - the cart's information should be sent from the client to the server.
This exacerbates the problem of high bandwidth usage, which is addressed by adding a rule about caching being explicitly permissible (or not) by responses. This way, intermediaries (who transfer information between the server and the client) can cache responses and return them to the client for identical requests without having to query the server, without worry that the information is stale.
Some more advantages attributed to REST
A REST service can be made such that it is used by easily available internet browsers instead of custom tailored software. And it is considered more fault resistant. Also, it is not bound to a specific method of communication so that communication can be done in different ways and through intermediaries.
Relationship to other technologies
SOAP - Very crudely, SOAP is used to describe a set of rules for how information is represented - it's XML with more specifics.
Example of a SOAP message. (Not crudely - see
the specifications at W3.org.). In this sense, it is not contradictory to REST. A REST service can reply to the initial request with the information that all requests and replies are to be sent in SOAP form. SOAP actually has much more defined, but it's not the scope of this post to deal with that.
HTTP - How, exactly, are the requests and replies sent between the client and server? Carrier pigeons aren't very useful, HTTP is.
This is all in theory. In practice - the term REST is often used more liberally. Sometimes meaning mainly not-SOAP.