Guiding Principles for REST
Reference: https://restfulapi.net/
Synchronous Request/Response: As HTTP itself is a request/response protocol, REST is a great fit for request/reply interactions.
Client-server: By separating the user interface concerns from the business logic and data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
Stateless: Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. REST APIs only take inputs and provides outputs. This does not mean however that a REST API cannot perform authentication and authorization. Authorization should be tokenized and sent on every request.
Cacheable: To properly scale a web application over the internet, a REST API must be able to easily mark its responses as cacheable or not. Cache constraints require that the data within a response to a request be implicitly or explicitly labelled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
Uniform interface: By applying the software engineering principles of generality to the component interface, the overall system architecture is simplified. REST is defined by four interface constraints:
identification of resources
manipulation of resources through representations
self-descriptive messages
hypermedia as the engine of application state
Layered system: The layered system style allows an architecture to be composed of hierarchical layers by constraining component behaviour such that each component cannot “see” beyond the immediate layer with which they are interacting.
Because REST APIs follow a well defined architectural pattern, tools such as Swagger can easily integrate into an application and document the endpoints, making it easier for other developers to pick up an endpoint’s intentions.
An example of a swagger documented API of a Java Spring Boot REST API service
Swagger is an automatic API documentation generator for REST APIs