Skip to main content

Core Principles of REST Design

REST (Representational State Transfer) is an architectural style for distributed systems based on stateless client-server communication. The core principles of REST design provide a robust and scalable foundation for the development of our APIs. To ensure the consistency and quality of our APIs, the principles outlined in this guideline MUST be implemented in accordance with the OpenAPI Specification.

By applying these REST architecture principles according to the OpenAPI Specification, we ensure that our APIs are uniform, well-documented, and easy to understand, greatly simplifying integration and usage.

Statelessness​

RESTful APIs MUST be stateless, meaning that each request from the client to the server MUST contain all the information necessary to process the request. The server MUST NOT store any client session data between requests. This improves scalability and reduces the complexity of the implementation.

Client-Server Interaction​

The client-server model separates the user interface (client) from data processing (server). This separation of responsibilities allows for more independent development, maintenance, and scaling of both client and server components. The client is responsible for the user interface and presentation logic, while the server handles the business logic and data management.

This abstraction is valuable because it enables the development of additional applications and products on the same unified data base, without requiring significant adjustments to server data for specific client components.

Too tight coupling between server and client can limit the flexibility and extensibility of the systems, hindering the innovation process. By separating data processing and presentation, different clients, applications, and services can access and utilize the same data, significantly facilitating the development of new features and products based on the existing infrastructure.

Cacheability​

To increase efficiency and reduce server load, API responses SHOULD be cacheable when appropriate. The responses MUST explicitly be marked as cacheable or non-cacheable to ensure that clients and intermediary servers know how to handle them.

Cache-Control Header​

Each API response MUST include a Cache-Control header to clearly define the caching policies.

Example for cacheable content:

Cache-Control: public, max-age=3600, s-maxage=86400, immutable
  • public: Indicates that the response can be cached by any cache (including CDNs and browsers).
  • max-age=3600: The maximum time, in seconds, that the browser should cache the response (here: 1 hour).
  • s-maxage=86400: The maximum time, in seconds, that CDNs should cache the response (here: 24 hours). This overrides max-age for shared caches.
  • immutable: Signals to the browser that the resource will never change.

Example for non-cacheable content:

Cache-Control: no-store

ETag Header​

Each resource-based response MUST include an ETag header to identify a unique version of the resource. This allows clients to fetch updated data only when the resource has changed.

Example:

ETag: "abc123xyz"

Last-Modified Header​

Each resource-based response SHOULD include a Last-Modified header to indicate the last time the resource was modified. This helps with validation and conditional requests.

Example:

Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

Cache Invalidation Strategy​

A clear cache invalidation strategy MUST be defined and documented to ensure that outdated or invalid data does not remain in the cache.

For example, by using:

Cache-Control: no-cache

for resources that are frequently updated.

Additionally, implementing webhooks or push mechanisms can be used to invalidate caches when changes occur.

Layered System​

The REST design MUST support a layered system, where a client does not need to know whether it is communicating directly with the end server or an intermediary server. This layered architecture can help improve security by introducing additional layers such as load balancers, authentication servers, and gateways without requiring any modifications to the client.

Example:

By implementing a load balancer as an intermediary server, traffic can be distributed across multiple servers to reduce load and increase availability. Additionally, an authentication server can be integrated into the architecture to ensure that only authorized clients have access to the API. The client does not need to be aware of these additional layers, as communication continues through the same API endpoints.

API systems should be designed to enable such stateless load distribution. This means that each request MUST be processed independently, without relying on previous interactions with the server. To ensure this, the API MUST include all necessary information in each request to process it independently.