Mark Pearl

REST stands for REpresentational State Transer. It is currently the de facto architecture of web applications. It is a guideline for mapping resources to URLs and interacting with them using CRUD verbs (Post, Get, Put and Delete).


Resources are best thought of as nouns. For example, the following is not RESTful because it uses a URL to describe an action. This is a fairly fundamental point in distinguishing RESTful from non-RESTful systems.


URLs should be as precise as needed; everything needed to uniquely identify a resource should be in the URL. You should not need to include data identifying the resource in the request. This way, URLs act as a complete map of all the data your application handles.

HTTP Verbs


GET is the simplest type of HTTP request method; the one that browsers use each time you click a link or type a URL into the address bar. It instructs the server to transmit the data identified by the URL to the client. Data should never be modified on the server side as a result of a GET request. In this sense, a GET request is read-only, but of course, once the client receives the data, it is free to do any operation with it on its own side - for instance, format it for display.


A PUT request is used when you wish to create or update the resource identified by the URL. For example,

PUT /clients/robin

might create a client, called Robin on the server. You will notice that REST is completely backend agnostic; there is nothing in the request that informs the server how the data should be created - just that it should. This allows you to easily swap the backend technology if the need should arise. PUT requests contain the data to use in updating or creating the resource in the body.


DELETE should perform the contrary of PUT; it should be used when you want to delete the resource identified by the URL of the request.


POST is used when the processing you wish to happen on the server should be repeated, if the POST request is repeated (that is, they are not idempotent; more on that below). In addition, POST requests should cause processing of the request body as a subordinate of the URL you are posting to.

In plain words:

POST /clients/

should not cause the resource at /clients/, itself, to be modified, but a resource whose URL starts with /clients/. For instance, it could append a new client to the list, with an id generated by the server.


PUT requests are used easily instead of POST requests, and vice versa. Some systems use only one, some use POST for create operations, and PUT for update operations (since with a PUT request you always supply the complete URL), some even use POST for updates and PUT for creates.

Often, POST requests are used to trigger operations on the server, which do not fit into the Create/Update/Delete paradigm; but this, however, is beyond the scope of REST. In our example, we’ll stick with PUT all the way.

Idempotent methods:

These methods achieve the same result, no matter how many times the request is repeated: they are GET, PUT, and DELETE. The only non idempotent method is POST.

PUT and DELETE being considered idempotent might be surprising, though, it, in fact, is quite easy to explain:

repeating a PUT method with exactly the same body should modify a resource in a way that it remains identical to the one described in the previous PUT request: nothing will change! Similarly, it makes no sense to delete a resource twice. It follows that no matter how many times a PUT or DELETE request is repeated, the result should be the same as if it had been done only once.

Remember: it’s you, the programmer, who ultimately decides what happens when a certain HTTP method is used. There is nothing inherent to HTTP implementations that will automatically cause resources to be created, listed, deleted, or updated. You must be careful to apply the HTTP protocol correctly and enforce these semantics yourself.

See Beginners guide to HTTP

Anemic REST Antipattern

Failure to properly model the domain as a set of resources, naively developing services that simply expose static, hierarchical data models via templated URL’s.

Read Thoughtworks Info on Antipattern

Rest & Long Running Jobs

Return a 202 Accepted Response

Rest and long running jobs

blog comments powered by Disqus

Want to get my personal insights on what I learn as I learn it? Subscribe now!