REST API Key Concepts and Requirements
Tags: webdev, api, programming
Published: 2023-04-21 22:15:06

RESTful APIs are a type of web API, which can be understood as a gateway between clients and resources on the web. Clients, which could be a person or another software system, interact with resources, such as images, videos, text, numbers, or any type of data, through this API. 

This exchange is managed by the server, which is the machine providing the resource. APIs are designed to maintain security, control, and authentication, and they determine which clients get access to specific internal resources​​.

REST, which stands for Representational State Transfer, is a software architectural style that provides guidelines for how an API should work. 

It was initially created to manage communication on complex networks like the internet, offering support for high-performing and reliable communication at scale. 

APIs that follow the REST architectural style are called REST APIs or RESTful APIs interchangeably. Web services implementing this architecture are referred to as RESTful web services​.

## 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](https://restfulapi.net/statelessness/). 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](https://dev.to/colinmcdermott/restful-api-design-cheatsheet-2ji6)
- [API Rate Limiting Cheat Sheet](https://dev.to/colinmcdermott/api-rate-limiting-cheat-sheet-409f)