rest - What exactly is RESTful programming?

ID : 93

viewed : 229

Tags : resthttparchitecturedefinitionrest

Top 5 Answer for rest - What exactly is RESTful programming?

vote vote


REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The key constraint is that the server and client must both agree on the media used, which in the case of the web is HTML.

An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. An HTML form is an example of this: The server specifies the location of the resource and the required fields. The browser doesn't know in advance where to submit the information, and it doesn't know in advance what information to submit. Both forms of information are entirely supplied by the server. (This principle is called HATEOAS: Hypermedia As The Engine Of Application State.)

So, how does this apply to HTTP, and how can it be implemented in practice? HTTP is oriented around verbs and resources. The two verbs in mainstream usage are GET and POST, which I think everyone will recognize. However, the HTTP standard defines several others such as PUT and DELETE. These verbs are then applied to resources, according to the instructions provided by the server.

For example, Let's imagine that we have a user database that is managed by a web service. Our service uses a custom hypermedia based on JSON, for which we assign the mimetype application/json+userdb (There might also be an application/xml+userdb and application/whatever+userdb - many media types may be supported). The client and the server have both been programmed to understand this format, but they don't know anything about each other. As Roy Fielding points out:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

A request for the base resource / might return something like this:


GET / Accept: application/json+userdb 


200 OK Content-Type: application/json+userdb  {     "version": "1.0",     "links": [         {             "href": "/user",             "rel": "list",             "method": "GET"         },         {             "href": "/user",             "rel": "create",             "method": "POST"         }     ] } 

We know from the description of our media that we can find information about related resources from sections called "links". This is called Hypermedia controls. In this case, we can tell from such a section that we can find a user list by making another request for /user:


GET /user Accept: application/json+userdb 


200 OK Content-Type: application/json+userdb  {     "users": [         {             "id": 1,             "name": "Emil",             "country: "Sweden",             "links": [                 {                     "href": "/user/1",                     "rel": "self",                     "method": "GET"                 },                 {                     "href": "/user/1",                     "rel": "edit",                     "method": "PUT"                 },                 {                     "href": "/user/1",                     "rel": "delete",                     "method": "DELETE"                 }             ]         },         {             "id": 2,             "name": "Adam",             "country: "Scotland",             "links": [                 {                     "href": "/user/2",                     "rel": "self",                     "method": "GET"                 },                 {                     "href": "/user/2",                     "rel": "edit",                     "method": "PUT"                 },                 {                     "href": "/user/2",                     "rel": "delete",                     "method": "DELETE"                 }             ]         }     ],     "links": [         {             "href": "/user",             "rel": "create",             "method": "POST"         }     ] } 

We can tell a lot from this response. For instance, we now know we can create a new user by POSTing to /user:


POST /user Accept: application/json+userdb Content-Type: application/json+userdb  {     "name": "Karl",     "country": "Austria" } 


201 Created Content-Type: application/json+userdb  {     "user": {         "id": 3,         "name": "Karl",         "country": "Austria",         "links": [             {                 "href": "/user/3",                 "rel": "self",                 "method": "GET"             },             {                 "href": "/user/3",                 "rel": "edit",                 "method": "PUT"             },             {                 "href": "/user/3",                 "rel": "delete",                 "method": "DELETE"             }         ]     },     "links": {        "href": "/user",        "rel": "list",        "method": "GET"     } } 

We also know that we can change existing data:


PUT /user/1 Accept: application/json+userdb Content-Type: application/json+userdb  {     "name": "Emil",     "country": "Bhutan" } 


200 OK Content-Type: application/json+userdb  {     "user": {         "id": 1,         "name": "Emil",         "country": "Bhutan",         "links": [             {                 "href": "/user/1",                 "rel": "self",                 "method": "GET"             },             {                 "href": "/user/1",                 "rel": "edit",                 "method": "PUT"             },             {                 "href": "/user/1",                 "rel": "delete",                 "method": "DELETE"             }         ]     },     "links": {        "href": "/user",        "rel": "list",        "method": "GET"     } } 

Notice that we are using different HTTP verbs (GET, PUT, POST, DELETE etc.) to manipulate these resources, and that the only knowledge we presume on the client's part is our media definition.

Further reading:

(This answer has been the subject of a fair amount of criticism for missing the point. For the most part, that has been a fair critique. What I originally described was more in line with how REST was usually implemented a few years ago when I first wrote this, rather than its true meaning. I've revised the answer to better represent the real meaning.)

vote vote


An architectural style called REST (Representational State Transfer) advocates that web applications should use HTTP as it was originally envisioned. Lookups should use GET requests. PUT, POST, and DELETE requests should be used for mutation, creation, and deletion respectively.

REST proponents tend to favor URLs, such as 

but the REST architecture does not require these "pretty URLs". A GET request with a parameter 

is every bit as RESTful.

Keep in mind that GET requests should never be used for updating information. For example, a GET request for adding an item to a cart 

would not be appropriate. GET requests should be idempotent. That is, issuing a request twice should be no different from issuing it once. That's what makes the requests cacheable. An "add to cart" request is not idempotent—issuing it twice adds two copies of the item to the cart. A POST request is clearly appropriate in this context. Thus, even a RESTful web application needs its share of POST requests.

This is taken from the excellent book Core JavaServer faces book by David M. Geary.

vote vote


RESTful programming is about:

  • resources being identified by a persistent identifier: URIs are the ubiquitous choice of identifier these days
  • resources being manipulated using a common set of verbs: HTTP methods are the commonly seen case - the venerable Create, Retrieve, Update, Delete becomes POST, GET, PUT, and DELETE. But REST is not limited to HTTP, it is just the most commonly used transport right now.
  • the actual representation retrieved for a resource is dependent on the request and not the identifier: use Accept headers to control whether you want XML, HTTP, or even a Java Object representing the resource
  • maintaining the state in the object and representing the state in the representation
  • representing the relationships between resources in the representation of the resource: the links between objects are embedded directly in the representation
  • resource representations describe how the representation can be used and under what circumstances it should be discarded/refetched in a consistent manner: usage of HTTP Cache-Control headers

The last one is probably the most important in terms of consequences and overall effectiveness of REST. Overall, most of the RESTful discussions seem to center on HTTP and its usage from a browser and what not. I understand that R. Fielding coined the term when he described the architecture and decisions that lead to HTTP. His thesis is more about the architecture and cache-ability of resources than it is about HTTP.

If you are really interested in what a RESTful architecture is and why it works, read his thesis a few times and read the whole thing not just Chapter 5! Next look into why DNS works. Read about the hierarchical organization of DNS and how referrals work. Then read and consider how DNS caching works. Finally, read the HTTP specifications (RFC2616 and RFC3040 in particular) and consider how and why the caching works the way that it does. Eventually, it will just click. The final revelation for me was when I saw the similarity between DNS and HTTP. After this, understanding why SOA and Message Passing Interfaces are scalable starts to click.

I think that the most important trick to understanding the architectural importance and performance implications of a RESTful and Shared Nothing architectures is to avoid getting hung up on the technology and implementation details. Concentrate on who owns resources, who is responsible for creating/maintaining them, etc. Then think about the representations, protocols, and technologies.

vote vote


This is what it might look like.

Create a user with three properties:

POST /user fname=John&lname=Doe&age=25 

The server responds:

200 OK Location: /user/123 

In the future, you can then retrieve the user information:

GET /user/123 

The server responds:

200 OK <fname>John</fname><lname>Doe</lname><age>25</age> 

To modify the record (lname and age will remain unchanged):

PATCH /user/123 fname=Johnny 

To update the record (and consequently lname and age will be NULL):

PUT /user/123 fname=Johnny 
vote vote


A great book on REST is REST in Practice.

Must reads are Representational State Transfer (REST) and REST APIs must be hypertext-driven

See Martin Fowlers article the Richardson Maturity Model (RMM) for an explanation on what an RESTful service is.

Richardson Maturity Model

To be RESTful a Service needs to fulfill the Hypermedia as the Engine of Application State. (HATEOAS), that is, it needs to reach level 3 in the RMM, read the article for details or the slides from the qcon talk.

The HATEOAS constraint is an acronym for Hypermedia as the Engine of Application State. This principle is the key differentiator between a REST and most other forms of client server system.


A client of a RESTful application need only know a single fixed URL to access it. All future actions should be discoverable dynamically from hypermedia links included in the representations of the resources that are returned from that URL. Standardized media types are also expected to be understood by any client that might use a RESTful API. (From Wikipedia, the free encyclopedia)

REST Litmus Test for Web Frameworks is a similar maturity test for web frameworks.

Approaching pure REST: Learning to love HATEOAS is a good collection of links.

REST versus SOAP for the Public Cloud discusses the current levels of REST usage.

REST and versioning discusses Extensibility, Versioning, Evolvability, etc. through Modifiability

Top 3 video Explaining rest - What exactly is RESTful programming?