API design is the process of creating well-structured interfaces for programmatic access to system capabilities, centered on the REST (Representational State Transfer) architectural style — a set of constraints that shape how web services interact over HTTP. Good API design balances discoverability, consistency, and performance, enabling developers to predict behavior, integrate quickly, and build reliably at scale. As AI agents now consume APIs alongside humans, well-structured machine-readable specifications (OpenAPI, llms.txt) have become as important as human-readable documentation. The key insight: RESTful design is not just about using HTTP verbs — it's about treating resources as first-class citizens, embracing statelessness, and designing for both human developers and autonomous systems that must understand, invoke, and recover from your API without human intervention.
What This Cheat Sheet Covers
This topic spans 33 focused tables and 257 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: REST Architectural Constraints
The six REST constraints defined by Roy Fielding form the theoretical backbone of every RESTful API. Understanding which constraint solves which problem — and which one is optional — prevents misapplying the term "RESTful" to RPC-style designs.
| Constraint | Example | Description |
|---|---|---|
Client: Mobile appServer: API backend | • Separation of concerns between user interface and data storage • clients and servers evolve independently without tight coupling. | |
Authorization: Bearer <token> | • Each request contains all necessary context (auth, params) • server stores no session state between requests, improving scalability and reliability. | |
Cache-Control: max-age=3600ETag: "abc123" | • Responses explicitly labeled cacheable or not • reduces server load and latency by allowing clients and intermediaries to reuse responses. |