REST API Design principles

Why REST API

One of the Questions that was asked recently was why do we have to use REST and not something else such as SOAP or the traditional method of file transfer or even gRPC. All that is required to be passed between the system is data. Having been working for so long in this area, this got my tongue because all this while I was focussed on how to make use of APIs to satisfy a specific functionality. I hadn't thought about the  "Why" part in detail i.e what are the design considerations/constraints that led to REST API

In this post we will look at some of the design principles that underpins REST APIs. 

Before that lets look at it all worked in Non-REST World

Traditional Approach

As someone who has been working in Telco domain, the fundamental aspect of communication between the systems was using a protocol which is usually defined by a standards organization(such as RFC, 3gpp and so on).

A protocol as you might know  are a set of rules that has to be followed by all the involved parties in the system. Following were some of the patterns under which they operated in

Lack of Client-Server separation

Before systems start exchanging any data , they first have to make other systems aware of your capabilities and know other system's capabilities too. During this process whilst they establish a standard process of communication, what gets blurred is a clear identification of Client and Server. 

Problem : Since there is no clear separation of who is acting as a Client and server, it puts onus on each of them to periodically share "I know you, you know me" kind of information. 

What's Relevance to REST : Primary design constraint of REST is there should be a clear separation of concerns of a Client and Server   

Statefulness 

To maintain the communication intact, it becomes important for a system to maintain the remember what other system is doing. If not there will be frequent exchange of "I know you, you know me" messages which will only flood the traffic 

Problem : In this case each system has to remember the state of other systems. This is heavy processing if this is to viewed in larger systemic context 

What's Relevance to REST :  REST defines that once Client and Server roles are clearly defined, there is no requirement of "Statefulness" to be maintained in the systems

 
Adaptability for change

Its impossible that a system will stay constant over a period of time. Additional features and capabilities will be developed. If the changes involved impacts the communication, then it has to communicated to the other systems. This puts a major issue where connected systems should decide on whether to retain this connection or update themselves. 

Problem : There is a significant impact of a system's change or evolution on dependent systems. 

Lack of Abstraction

Because the exchange of data is bound by the rules defined in the protocol, it requires the system to implement this protocol in a similar way. The business logic that is required to perform the data exchange has to be implemented and understood by all the systems involved. 

Problem : Lack of abstraction where each system knows the Business logic of other systems as to how data exchange is happening and how data is being utilized

What's Relevance to REST : To ensure abstraction REST proposes Layered system approach where all Client is required to know if how it connects to Server and its capabilities/features, it need not know the details thereby abstracting the Business logic. 

With these design principles in place, I will cover the "What" aspects of REST API that focuses different methodologies adopted and how to design a REST API