RESTful design

RESTful design depends on six constraints. These constraints are “shoulds” instead of “musts,” reflecting the fact that REST is essentially a set of guidelines for an HTTP resource-based architecture:

1. Uniform interface: REST APIs should have a uniform interface. In other words, the requesting client device should not matter; a mobile device, an IoT (internet of things) device, and a laptop must all be able to access a server in the same way.

2. Client/server: REST APIs should have a client/server architecture. Clients are the consumers requesting information, and servers are the providers of that information.

3. Stateless: REST APIs should not require stateful communications. REST APIs do not maintain state during communication; it is as though each request is the first one received by the server. The consumer will therefore need to supply everything the provider will need in order to act upon the request. This has the benefit of saving the provider from having to remember the consumer from one request to another. Consumers often provide tokens to create a state-like experience.

4. Cacheable: The response from the REST API provider should indicate whether the response is cacheable. Caching is a method of increasing request throughput by storing commonly requested data on the client side or in a server cache. When a request is made, the client will first check its local storage for the requested information. If it doesn’t find the information, it passes the request to the server, which checks its local storage for the requested information. If the data is not there either, the request could be passed to other servers, such as database servers, where the data can be retrieved. As you might imagine, if the data is stored on the client, the client can immediately retrieve the requested data at little to no processing cost to the server. This also applies if the server has cached a request. The further down the chain a request has to go to retrieve data, the higher the resource cost and the longer it takes. Making REST APIs cacheable by default is a way to improve overall REST performance and scalability by decreasing response times and server processing power. APIs usually manage caching with the use of headers that explain when the requested information will expire from the cache.

5. Layered system: The client should be able to request data from an endpoint without knowing about the underlying server architecture.

6. Code on demand (optional): Allows for code to be sent to the client for execution

By source: "Hacking APIs : breaking web application programming interfaces" by Corey Ball.