REST API Key Concepts and Requirements

Stateless

Each request from the client must contain all the necessary information for the server to process the request. The server should not store any information about the client's state between requests, making the API stateless. This principle allows for better scalability and easier maintenance.

Client-Server Architecture

A REST API is based on a client-server architecture, where the client is responsible for the user interface and the server handles data storage and processing. This separation of concerns allows for improved flexibility, scalability, and maintainability.

Cacheability

To optimize performance, REST APIs should support caching. Responses from the server should indicate whether they can be cached or not, so the client can reuse cached responses when appropriate. This reduces the load on the server and improves overall performance.

Layered System

A REST API should be built using a layered architecture, where each layer performs a specific function. This separation of concerns makes it easier to maintain and evolve the system over time. For example, an API might have a security layer, a business logic layer, and a data access layer.

Uniform Interface

A REST API should have a consistent and uniform interface, which simplifies its usage and makes it more intuitive. This involves using standard HTTP methods, clear resource naming conventions, and providing descriptive error messages.

Code on Demand (optional)

While not always implemented, REST APIs can support the ability to extend client functionality through downloadable code, such as JavaScript. This feature can be useful in specific scenarios but is not a mandatory requirement for a REST API.

Idempotency

Idempotent operations are those that can be performed multiple times without changing the result beyond the initial application. In the context of REST APIs, GET, PUT, and DELETE methods should be idempotent, ensuring that repeated requests have the same effect as a single request.

Resource Nesting

In some cases, it makes sense to nest resources within other resources to represent relationships. For example, you might represent a user's comments on a blog post with a URL like /posts/123/comments. Use nesting sparingly and only when it reflects the natural hierarchy of the data.

Filtering, Sorting, and Searching

In addition to basic filtering and sorting, consider implementing more advanced search capabilities for your API, such as full-text search or complex querying. This allows clients to quickly locate and retrieve relevant resources.

Also check out:

• RESTful API Design Cheatsheet
• API Rate Limiting Cheat Sheet