REST API Principles

3 min readJul 24, 2022

The majority of enterprise integrations, as well as most websites, mobile applications, and other web services, are powered by REST APIs. The way businesses implement RESTful web services is far more flexible than it was for the earlier generation of web services, such as SOAP and XML-RPC.

API

An Application Programming Interface (API) is a way for two or more computer programs to communicate with each other. It is considered a set of definitions and protocols for building and integrating application software. While, an API specification is a document or standard that outlines how to build or use this kind of interface or protocol.

REST

REST is an acronym for REpresentational State Transfer and an architectural style for distributed hypermedia systems. REST is cosidered as guiding principles and constraints and not a protocol or a standard. Generally, REST describes a uniform interface between decoupled components in the Internet in a Client-Server architecture, it can be developed in a variety of ways.

REST API

Any API (Web API or Web Service) conforming to the REST architectural style principles is called a REST API or RESTful API. REST architectural style defines six principles, that must be satisfied if a service interface needs to be referred to as RESTful.

REST Architectural constraints

These constraints, applied to the architecture, were originally communicated by Roy Fielding in his doctoral dissertation in 2000.

Client–server architecture

The architecture should be made up of clients, servers, and resources, with requests managed through HTTP, enforcing the principle of separation of concerns.

Statelessness

Statelessness mandates that each request from the client to the server must contain all of the information necessary to understand and complete the request. And therefore, the client must entirely keep the session state.

Cacheability

Responses must, implicitly or explicitly, define themselves as either cacheable or non-cacheable, providing th capability to the clients and intermediaries to cache responses. And also, to prevent clients from providing stale or inappropriate data in response to further requests.

Layered system

It means that if a proxy or load balancer is placed between the client and server, it won’t affect their communications, and there won’t be a need to update the client or server code.

Code on demand (optional)

REST architecture allows client functionality to extend by downloading code from the server and executing it in the form of applets or scripts.

Uniform interface

A uniform interface implifies and decouples the architecture, which enables each part to evolve independently. REST defines four interface constraints:

Identification of resources

The resources themselves are conceptually separate from the representations that are returned to the client.

Manipulation of resources

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.

Self-descriptive messages

The messages returned to the client should have enough information to describe how the client should process it.

hypermedia as the engine of application state (HATEOAS)

The clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). While the services deliver state to clients via body content, response codes, and response headers.

REST and HTTP are Not the Same

While REST refers to a set of principles of a particular architectural style, HTTP is a well-defined protocol that to provides many features of a RESTful system. It important to note that many people continue to use interchangeably the terms REST and HTTP, while they are different things.