What is REST API

What is REST API

Representational state transfer (REST) is an architectural style designed to take advantage of existing protocols like HTTP/HTTPS. REST defines a set of constraints to be used for creating APIs. When an API is designed based on the principles which adheres to the Representational state transfer architectural style it is called a RESTful API. Unlike SOAP services, RESTful APIs are not constrained to one particular data type like XML. Instead, RESTful APIs can return any type of data format like JSON, YAML, XML, TEXT etc depending on the client request. Also the datatype is independent of the methods and resources.

REST was designed by Roy Fielding in his 2000 PhD dissertation "Architectural Styles and the Design of Network-based Software Architectures".

Throughout the HTTP standardization process, I was called on to defend the design choices of the Web. That is an extremely difficult thing to do within a process that accepts proposals from anyone on a topic that was rapidly becoming the center of an entire industry. I had comments from well over 500 developers, many of whom were distinguished engineers with decades of experience, and I had to explain everything from the most abstract notions of Web interaction to the finest details of HTTP syntax. That process honed my model down to a core set of principles, properties, and constraints that are now called REST.

One of the key advantages of REST APIs is that they are flexible. Datatype is not tied to resources or methods. This kind of flexibility allows developers to design an API that meets diverse requirements.

Understanding REST API Design

A RESTful system is based on 6 guiding constraint. Most of the RESTful APIs do not follow the REST requirements and constraints set by Dr. Roy Fielding. It’s important to understand what makes a REST API RESTful, and why these constraints exist before building your API. Lets look into the six princicles which makes an API RESTful.

  • Client-Server
  • Stateless
  • Cache
  • Uniform Interface
  • Layered System
  • Code on Demand


The Client-Server constraint concept is seperation of concern. This means that the client and the server is decoupled and independent of each other and any changes made to client or the server does not impact the other. This constraint allows the client and the server to grow and scale independent of each other.


The request-response between client-server is stateless which means there is no data stored on the server side to determince the action of the request call. Each request made is independent of one another, and each call contains all of the data necessary to complete the request successfully. This constraint improves APIs reliability by not storing the state. If necessary the session state is stored on the client side.


The Cache constraint partially or completely eliminates the client-server interaction by caching the response. Due to the Stateless constraint, the server will be bombarded with too many requests even if the response does not change. By implementing cache, the requests to the server is reduced. The response should always be defined cacheable or non-cacheable and if it is cacheable then cache expiry time should be provided. Caching improves scalability and performance of an API.

Uniform Interface:

The uniform Interface constraint is fundamental in designing any RESTful architecture. This constraint decouples the systems involved in the architecture and makes it easier for the systems to scale independently. There are 4 constraints to the uniform interface which are:

Resource identification in requests:

Each resource are identified individually in the request which are identified using Uniform Resource Identifier (URI) parameter in the request URL. The resources data representation or the data format is independent of what is sent to a client as a response. For example, a mobile client can make a request to get a recource in the JSON representation while another web client can make a request to get the resource in XML representation.

Resource manipulation through representations:

HTML, XML, JSON, PNG, etc formats are representations of the identified resource. RESTful applications may support different representation of the same resource under the same URI by allowing clients to indicate which representation of a resource they wish to receive via the Accept HTTP header parameter. Resources can be updated (or created) by sending representations from the client to the server. RESTful applications may support more than one representation for updates to the same resource.

Self-descriptive messages:

All client-request and the server response is a message. Each message includes contains all the information necessary to describe how to process the message.

Hypermedia as the engine of application state (HATEOAS):

To simply put, with HATEOAS constraint the server response contains hypermedia links for further action on the resource. This is the magic of RESTful API.

Layered system:

The layered system architecture consists of different layers ^such as proxy layser, security layer, etc. This also makes it easy to scale the system layers independent of each other.

Code on demand:

This is the only OPTIONAL constraint in the REST architectural design. REST allows client functionality to be extended by sending code in the form of applets or scripts via a response. This simplifies clients by reducing the number of features required to be pre-implemented.

Richardson Maturity Model:

API maturity level is determined using the Richardson Maturity Model. Learn more about Richardson Maturity Model (RMM).