📄️ Introduction
Welcome to the Rest API Design handbook.
📄️ Application Programming Interface
API stands for Application Programming Interface.
📄️ Life Cycle
1. Planning / Requirements Gathering
📄️ Constraints
1. Client-Server Architecture
📄️ Resource Design
Resource Naming Conventions
📄️ Richardson
The Richardson Maturity Model (RMM) is a model developed by Leonard Richardson to evaluate how well a web API follows REST principles. It defines four levels (0 to 3), each building on the previous one, showing the maturity of an API in terms of its RESTful characteristics.
📄️ Partial Response
Partial Response is a REST API design technique where clients can request only specific fields or properties of a resource rather than the entire resource.
📄️ Error Response
What Are Meaningful Error Responses
📄️ Cache Control
Cache control in REST API design refers to how a server communicates caching policies to clients and intermediaries (like browsers, proxies, and CDNs) using HTTP headers. Proper cache control helps improve performance, reduce server load, and provide a better user experience by avoiding unnecessary repeat requests.
📄️ E-Tag
ETag (short for Entity Tag) is a mechanism used in HTTP headers to manage web cache validation and optimistic concurrency control. It is part of the HTTP specification (defined in RFC 7232) and is commonly used in REST APIs to:
📄️ API Versioning
REST API versioning is the practice of managing changes to a RESTful API by creating different versions of the API.
📄️ Changes
Non-Breaking Change
📄️ Code First
The Code-First approach (also known as bottom-up) is a way of designing REST APIs where you start by writing code first—typically the actual backend logic and route handlers—and then (optionally) generate documentation or OpenAPI (Swagger) specs from the existing code.
📄️ Design First
The Design-First approach (also known as top-down) means you define your API contract first—typically using OpenAPI/Swagger, RAML, or API Blueprint—before writing any backend code. This contract serves as a single source of truth for developers, frontend/backend teams, QA, and clients.
📄️ API Specification
| Specification | Description |
📄️ OAuth
OAuth 2.0 is a delegation protocol — it lets users authorize applications to act on their behalf, granting access to resources via access tokens.
📄️ Max Retry
Max retry defines the maximum number of failed login attempts a user (or IP) can make within a certain time window. After exceeding this limit, further attempts are blocked temporarily or permanently, depending on policy.
📄️ Jail
Jail is a longer-term or permanent block applied when repeated abusive behavior is detected. It’s often triggered by:
📄️ Security Headers
Security headers are HTTP headers that help secure the communication between clients and servers. These headers protect APIs from a range of attacks such as cross-site scripting (XSS), clickjacking, content sniffing, and more.
📄️ API Management
Agent Based
📄️ Developer Portal
An API Developer Portal is a self-service platform that provides:
📄️ Authentication
Digest Authentication
📄️ Access Control
Permission-Based Access Control
📄️ Security Practices
HTTPS Everywhere
📄️ Input Validation
Input validation is the process of verifying that incoming request data:
📄️ Error Tracking
Error tracking is the process of detecting, recording, and analyzing errors that occur in a REST API, in real time or retrospectively, to help developers identify, diagnose, and fix issues quickly.
📄️ Standard Error Format
What Is RFC 7807?
📄️ Swagger Specification
OpenAPI Specification (OAS)
📄️ API Blueprint
API Blueprint is a markdown-based API description language designed to document REST APIs in a human-readable and machine-parsable format.
📄️ RAML
RAML is a YAML-based language for describing REST APIs with a strong emphasis on:
📄️ Postman Collections
A Postman Collection is a grouped set of API requests saved together in Postman.
📄️ Self Description
In REST, a self-descriptive message is a request or response that contains all the information needed to understand and process it, without relying on out-of-band documentation.
📄️ HATEOAS
HATEOAS is a REST constraint stating that:
📄️ Unit Testing
What Should Be Unit Tested in an API Endpoint
📄️ Integration Testing
Integration testing verifies that multiple components of a REST API work together correctly as a complete system.
📄️ API Monitoring
API Monitoring is the continuous process of tracking the availability, performance, and correctness of your API endpoints in real-time or at scheduled intervals.
📄️ Caching
Caching reduces the number of requests that need to hit the server, saving bandwidth, CPU cycles, and database queries. This is essential for highly scalable APIs, especially when serving thousands or millions of clients.
📄️ Rate Limiting
Rate limiting restricts how many requests a client can make to the API within a certain time window. It protects servers from being overloaded and ensures fair usage.
📄️ Quotas
Quotas are similar to rate limits but typically apply over longer periods or across multiple resources.
📄️ Async Processing
Asynchronous processing means the client sends a request, and instead of waiting for the task to finish, the server immediately responds with a task reference or status URL. The client can then poll or wait for notification when the task completes.
📄️ Webhooks
Webhooks are a way for a server to notify a client automatically when an event occurs or an asynchronous task completes. Instead of polling, the server calls a client-provided URL.