Representational State Transfer (REST) is a software architecture that was designed to ensure interoperability between different Internet computer systems. It defines a set of constraints to be used for creating Web services. Services that conform to the REST architecture are called RESTful Web services.

REST is just one type of architecture – SOAP web services is another example. Each of these architectures will have their own specific rules and operations.

Glossary of Terms

  • Resource : Any information that can be named can be a resource. For example a document or image, a temporal service , a collection of other resources, and so on. In other words resources are identifiers to any piece of interesting information the server can provide. It is a conceptual mapping to a set of entities.
  • Representation : REST components perform actions on a resource by using a representation to capture the current or intended state of that resource. A representation is a sequence of bytes. It consists of data, metadata describing the data. Metadata is in the form of name-value pairs. Name corresponds to a standard that defines the value’s structure and semantics.
  • URI / URL: URI (Uniform Resource Identifier), is a set of characters that is used to identify a resource. A URL (Uniform Resource Locator) is the most commonly used version of a URI. It is often called a web address.
  • Hypermedia : It is a nonlinear medium of information which includes graphics, audio, video, plain text and hyperlinks.

Architectural Constraints

A RESTful web service must adhere to the following REST architectural constraints

  1. Client – Server : Clear delineation between the client and server. Loose coupling of the client and server enables each to be independent of the other. This enhances scalability of the server components.
  2. Uniform Interface : Resources should be uniquely identifiable through a single URL. It should be possible to manipulate a resource. In order to maintain a uniform interface, interface constraints guide the behavior of components.
  3. Stateless : Client-Server operations should be stateless. Any state management that is required should take place on the client, not the server. Requests sent from a client to a server will contain required information to make the server understand the requests.
  4. Cacheable : Data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If the response is defined as cacheable, then the client cache can reuse the response data for equivalent responses in the future.
  5. Layered System : Architecture should be composed of hierarchical layers by constraining component behavior such that each layer cannot interact beyond the next immediate layer they are in.
  6. Code on Demand : An optional constraint and is used the least. It allows client functionality to be extended by downloading and executing code in the form of applets or scripts.

Interface Constraints

In order to obtain a uniform interface, below constraints guide the behavior of components

  • Resource identification : Each resource must be uniquely identifiable via an URI. The identifier must be stable even when the underlying resource is updated. For example is a URI that might return a list of users. The resulting list of users is the resource. Representation of the response could be a Media Type specified by text/html or application/json.
  • Resource Manipulation using representations : An identified resource can be returned in various formats such as HTML, XML, JSON, PNG. These formats are representations of the identified resource. A RESTful applications allow clients to indicate which representation of a resource they wish to receive. Resources can be updated (or added) by sending representations from the client to the server. A RESTful applications allow clients to indicate their preferred representation when sending data to the server.
  • Self-descriptive messages : A message should contain enough information to describe how to process it. HTTP message type GET, HEAD and OPTIONS are read-only messages. HTTP message type PUT, POST and DELETE are update messages. There are well-defined rules for how clients and servers are expected to behave when using these messages.
  • Hypermedia as the engine of application state : A web page is an instance of application state. Hypermedia is text with hyperlinks within the webpage. During web surfing the web, hypermedia is used as the engine of application state. In this way, a RESTful application enables the server to inform the client of the possible ways to change the state of the application via hypermedia.

Client – Server Communication

A client send requests to retrieve or modify resources. Server send responses to these requests. Let’s take a look at the standard ways to make requests and send responses.

Request Structure

A request generally consists of:

  • HTTP verb : It defines what kind of operation to perform. There are 4 basic HTTP verbs we use in requests to interact with resources in a REST system:
    • GET : Retrieve a specific resource or a collection of resources
    • POST : Create a new resource
    • PUT : Update a specific resource
    • DELETE : remove a specific resource by id
  • Path to a resource : It determines the resource requested in request sent by client. For example It is hierarchical and descriptive. It is accessing the order with id 12 for the customer with id 223. Paths should contain the information necessary to locate a resource with the degree of specificity needed.
  • Header : It allows the client to pass along information about the request. It can be used for many purposes, such as authentication and providing information about the body content. HTTP Headers are property-value pairs that are separated by a colon. For example, a client accessing a resource with id 33 in an articles resource on a server might send a GET request like this. Accept header field in this case is saying that the client will accept the content in text/html.
GET /articles/33
Accept: text/html
  • Optional Data : The data (also called as body or message) contains information to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests.

Response Structure

Server include a content-type in the header of the response when sending a data payload to the client. The content types are MIME Types, just as they are in the accept field of the request header. The content-type that the server sends back in the response should be one of the options that the client specified in the accept field of the request.

For example, when a client is accessing a resource with id 33 in an articles resource with this GET Request:

GET /articles/23
Accept: text/html, application/xhtml

The server might send back the content with the response header:

Status Code: 200 (OK)
Content-Type: text/html

Responses from the server contain status codes to alert the client to information about the success of the operation.


Representational state transfer