What is REST? What is RESTful Web API? What are the contraints of REST that makeup RESTful Web API?

What is REST (the Concept of REST)

Nowadays we hear about REST or RESTful everywhere in the Web development world but we rarely think about what REST actually is, and in fact there are a lot of misunderstandings around REST such as:

• REST is an architectural pattern for web applications like MVC
• REST is a protocol like SOAP
• If a web API is built on HTTP then it's a RESTful web API
• If a web API uses JSON then it's a RESTful web API   etc.

The Definition of REST

REST is the abbreviation of Representational State Transfer. By definition:

• REST is an architectural style for distributed systems. Here we consider a distributed system to be either a single client/server application, or multiple applications communicating through a network.

• REST is a set of constraints. Some of them apply to the architecture level design and others to the API level design. If a distributed system applies these constraints, we call it a RESTful distributed system. 

Here are the constraints that make up the REST architectural style: 

1. Client-Server - REST must be applied on a client-server system. If a system is not a client-server architecture, no matter how big/complex it is, it's impossible to apply REST architecture. 

2. Stateless - in REST architecture, the client uses a request to access the target resource on the server and the server uses a response to return the proper result back to client. Each request from any client contains all the information necessary for the server to interpret the request and take the necessary actions. The server won't cache any client or session related data. If needed, the client can cache the data for future requests. Note the following two points:

• Usually a RESTful system is built on HTTP, and HTTP is stateless, which means HTTP doesn't break the the stateless constraint in REST. But if you are a web developer, you may be aware that we can use the session object to keep some state between the web server and web client.
• Stateless means there is no session state kept on the server. While the state in Representational State Transfer is not the session state, it's the state of resources that are carried by the representation.

3. Cache - in order to improve network efficiency, the client (or other components) has the ability to cache the responses.

4. Uniform Interface - the emphasis on a uniform interface between components is the central feature that distinguishes the REST architectural style from other network-based styles. Actually, there are a lot of ways to unify the interfaces between web application components, but REST chooses the most natural way - to leverage HTTP methods. To achieve a uniform interface, there are some API level design constraints to follow:

• Identification of resources
• Manipulation of resources through representations
• Self-descriptive messages
• Hypermedia as the engine of application state (HATEOAS)

5. Layered System - to improve the scalability and reduce the dependency chaos of a large system, the best way is to organize components into different functional layers. Each layer has dedicated tasks, can share a cache, security, and load balancing.

6. Code on demand - REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. For example, there are some pre-implemented client side code snippets, such as JavaScript code, Flash content or Java Applets, stored on a server. The client can fetch these from the server and execute them to run the pre-defined logic. We consider this is an optional constraint because it's rarely seen in a web service system.

Applying REST Constraints

• Roughly there are three generations of technology to build web APIs and expose the server side computing powers to clients across the web.
• The first generation is known as Remote Procedure Call (RPC), such as Common Object Request Broker Architecture (CORBA).
• The second generation is known as Web Services Description Language (WSDL) and Simple Object Access Protocol (SOAP) based technologies such as Windows Communication Foundation (WCF).
• The third generation is a RESTful Web Service. Once we apply the constraints of REST architectural style correctly, when designing and implementing a web service, this web service becomes a RESTful Web Service. In daily communication, we still call those non-RESTful web services Web Service, and call RESTful Web Services RESTful Web API or just Web API.

There are a lot of technologies we can use to build RESTful Web APIs, such as ASP.NET Core, ASP.NET MVC, NodeJS, Spring MVC, etc.
When we apply the constraints of the REST architectural style, some of the constraints are necessary and others are optional. Here is a check list:

1. Client-Server - as a web based system, this is, naturally, a MUST -have
2. Stateless - MUST have
3. Cache - nice to have, especially for large systems
4. Uniform Interface - the central feature MUST-have
   
   • Identification of resources - MUST-have
   • Manipulation of resources through representations - MUST-have
   • Self-descriptive messages - MUST-have
   • Hypermedia as the engine of application state (HATEOAS) - nice to have
5. Layered System - nice to have, especially for large systems
6. Code on demand - optional

☺Happy Learning.