What is REST

REST is an acronym for REpresentational State Transfer and an architectural style for distributed hypermedia systems. Roy Fielding first presented it in 2000 in his famous dissertation.

Like other architectural styles, REST has its guiding principles and constraints. These principles must be satisfied if a service interface needs to be referred to as RESTful.

A Web API (or Web Service) conforming to the REST architectural style is a REST API.

1. Guiding Principles of REST

The six guiding principles or constraints of the RESTful architecture are:

1.1. Uniform Interface

By applying the principle of generality to the components interface, we can simplify the overall system architecture and improve the visibility of interactions.

Multiple architectural constraints help in obtaining a uniform interface and guiding the behavior of components.

The following four constraints can achieve a uniform REST interface:

  • Identification of resources – The interface must uniquely identify each resource involved in the interaction between the client and the server.
  • Manipulation of resources through representations – The resources should have uniform representations in the server response. API consumers should use these representations to modify the resources state in the server.
  • Self-descriptive messages – Each resource representation should carry enough information to describe how to process the message. It should also provide information of the additional actions that the client can perform on the resource.
  • Hypermedia as the engine of application state – The client should have only the initial URI of the application. The client application should dynamically drive all other resources and interactions with the use of hyperlinks.

1.2. Client-server

The client-server design pattern enforces the separation of concerns, which helps the client and the server components evolve independently.

By separating the user interface concerns (client) from the data storage concerns (server), we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.

While the client and the server evolve, we have to make sure that the interface/contract between the client and the server does not break.

1.3. Stateless

Statelessness mandates that each request from the client to the server must contain all of the information necessary to understand and complete the request.

The server cannot take advantage of any previously stored context information on the server.

For this reason, the client application must entirely keep the session state.

1.4. Cacheable

The cacheable constraint requires that a response should implicitly or explicitly label itself as cacheable or non-cacheable.

If the response is cacheable, the client application gets the right to reuse the response data later for equivalent requests and a specified period.

1.5. Layered system

The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior.

For example, in a layered system, each component cannot see beyond the immediate layer they are interacting with.

1.6. Code on demand (optional)

REST also allows client functionality to extend by downloading and executing code in the form of applets or scripts.

The downloaded code simplifies clients by reducing the number of features required to be pre-implemented. Servers can provide part of features delivered to the client in the form of code, and the client only needs to execute the code.

2. What is a Resource?

The key abstraction of information in REST is a resource. Any information that we can name can be a resource. For example, a REST resource can be a document or image, a temporal service, a collection of other resources, or a non-virtual object (e.g., a person).

The state of the resource, at any particular time, is known as the resource representation.

The resource representations are consist of:

  • the data
  • the metadata describing the data
  • and the hypermedia links that can help the clients in transition to the next desired state.

A REST API consists of an assembly of interlinked resources. This set of resources is known as the REST API’s resource model.

2.1. Resource Identifiers

REST uses resource identifiers to identify each resource involved in the interactions between the client and the server components.

2.2. Hypermedia

The data format of a representation is known as a media type. The media type identifies a specification that defines how a representation is to be processed.

A RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure).

Hypertext (or hypermedia) means the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.

Remember that hypertext does not need to be HTML (or XML or JSON) on a browser. Machines can follow links when they understand the data format and relationship types.

— Roy Fielding

2.3. Self-descriptive

Further, resource representations shall be self-descriptive: the client does not need to know if a resource is an employee or a device. It should act based on the media type associated with the resource.

So in practice, we will create lots of custom media types – usually one media type associated with one resource.

Every media type defines a default processing model. For example, HTML defines a rendering process for hypertext and the browser behavior around each element.

Media Types have no relation to the resource methods GET/PUT/POST/DELETE/… other than the fact that some media type elements will define a process model that goes like “anchor elements with an href attribute create a hypertext link that, when selected, invokes a retrieval request (GET) on the URI corresponding to the CDATA-encoded href attribute.”

3. Resource Methods

Another important thing associated with REST is resource methods. These resource methods are used to perform the desired transition between two states of any resource.

A large number of people wrongly relate resource methods to HTTP methods (i.e., GET/PUT/POST/DELETE). Roy Fielding has never mentioned any recommendation around which method to be used in which condition. All he emphasizes is that it should be a uniform interface.

For example, if we decide that the application APIs will use HTTP POST for updating a resource – rather than most people recommend HTTP PUT – it’s all right. Still, the application interface will be RESTful.

Ideally, everything needed to transition the resource state shall be part of the resource representation – including all the supported methods and what form they will leave the representation.

We should enter a REST API with no prior knowledge beyond the initial URI (a bookmark) and a set of standardized media types appropriate for the intended audience (i.e., expected to be understood by any client that might use the API).

From that point on, all application state transitions must be driven by the client selection of server-provided choices present in the received representations or implied by the user’s manipulation of those representations.

The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on the fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

4. REST and HTTP are not same

Many people prefer to compare HTTP with REST. REST and HTTP are not the same.

REST != HTTP

Though REST also intends to make the web (internet) more streamlined and standard, Roy fielding advocates using REST principles more strictly. And that’s from where people try to start comparing REST with the web.

Roy fielding, in his dissertation, has nowhere mentioned any implementation direction – including any protocol preference or even HTTP. Till the time, we are honoring the six guiding principles of REST, which we can call our interface – RESTful.

5. Summary

In simple words, in the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs).

The resources are acted upon by using a set of simple, well-defined operations. Also, the resources have to be decoupled from their representation so that clients can access the content in various formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and others.

The clients and servers exchange representations of resources by using a standardized interface and protocol. Typically HTTP is the most used protocol, but REST does not mandate it.

Metadata about the resource is made available and used to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control.

And most importantly, every interaction with the server must be stateless.

All these principles help RESTful applications to be simple, lightweight, and fast.

References:

Comments

      • The original sentence, “Till the time, you are honoring the 6 guiding principles of REST, you can call your interface RESTful” threw me. I interpret it to mean “Unless you honor the six guiding principles of REST, you cannot call your interface RESTful.” Rowan’s text is equally clear.

        Why not change the webpage text to make it clearer?

        Reply
    • Or a RESTed API.

      And if it’s migrating from being an API that isn’t RESTed to one that is, you can say it’s under arREST 😉

      Reply
  1. Regarding the 6th guiding principle – coding on demand, does this include single page application in which code is downloaded from a server to the UI when invoked?

    Reply
  2. “Another thing which will help you while building RESTful APIs is that query based API results should be represented by a list of links with summary information, not by arrays of original resource representations because the query is not a substitute for identification of resources.”

    I struggle to comprehend this without an example. Let us say, our API is supposed to retrieve data, such as employee data from database server in JSON format to be consumed by client app. What is “a list of links with summary information” that we can expect as the result of the API.
    Currently I am using PHP + Laravel. Maybe someone can explain or give an example of the above statement, preferably using Laravel routing statement.

    Reply
    • The article suggests using URIs and respective response structures as below.

      If we will provide full device information in search query results, the client may start using these URIs to get and utilize individual device information – Which is wrong.

      For example, '/devices?id=1' should never be alternative to '/devices/1'.

      <devices size="3">
      	<device id="1"> 
          	<link rel="self" href="/devices/1"/>
          	<name>apple-srx_201</name> 
          	<serialNumber>1111</serialNumber> 
              <connectionStatus>up</connectionStatus> 
          </device> 
          <device id="2"> 
          	<link rel="self" href="/devices/2"/>
          	<name>apple-srx_202</name> 
          	<serialNumber>2222</serialNumber> 
              <connectionStatus>down</connectionStatus> 
          </device> 
          <device id="3"> 
          	<link rel="self" href="/devices/3"/>
          	<name>apple-srx_203</name> 
          	<serialNumber>3333</serialNumber> 
              <connectionStatus>up</connectionStatus> 
          </device> 
      </devices>
      <device id="1"> 
          <link rel="self" href="/devices/1"/>
          <deviceFamily>apple-es</deviceFamily> 
          <OSVersion>10.3R2.11</OSVersion> 
          <platform>SRX100B</platform> 
          <serialNumber>32423457</serialNumber> 
          <connectionStatus>up</connectionStatus> 
          <ipAddr>192.168.21.9</ipAddr> 
          <name>apple-srx_200</name> 
          <status>active</status>
      </device> 
      Reply
  3. > So in practice, you will end up creating lots of custom media-types – normally one media-type associated with one resource.

    Put in this way, IMHO, I think the sentence is misleading. Reading the phrase what I understand is that for each resource I MUST create a custom media type, for example application/vnd.book+json, application/vnd.author+json and application/vnd.user+json if my application handles book, author and user resources. Albeit this is not forbidden by the REST principles I think that a more appropriate sentence would be:

    > So in practice, you CAN end up creating lots of custom media-types – POTENTIALLY one media-type associated with one resource.

    Reply
  4. In the article you said “In simplest words, in the REST architectural style, data and functionality are considered resources…”, can you give an example of a functionality as a resource?

    Reply
    • PHP Laravel works on restful api features…
      There each request send and received through only with these 6 features….

      Reply
      • No, Laravel simulate PUT with POST and just sends a hidden field along containing “_PUT” with the form data identifying the POST as intending to PUT. It will not accept a real HTTP put.

        Reply
    • Consider the example of Google Maps API. You provide the source and destination and the API will give you the list of waypoints(route) to your destination.

      Reply
    • He gave the following examples in another topic:

      /api.example.com/cart-management/users/{id}/cart/checkout
      /api.example.com/song-management/users/{id}/playlist/play

      I think these are examples of functionality

      Reply
  5. What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

    Reply

Leave a Comment