API Design Principles and Best Practices Cheat Sheet

Updated 2026-05-28

Next Topic: Behavior-Driven Development (BDD) Cheat Sheet

🧠Study flashcards on this topic233 cards · spaced repetition→

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, 233 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: REST Architectural ConstraintsTable 2: Richardson Maturity Model LevelsTable 3: HTTP Methods and Idempotency GuaranteesTable 4: Resource Naming ConventionsTable 5: HTTP Status Code Best PracticesTable 6: Error Response Design (RFC 9457 Problem Details)Table 7: Pagination StrategiesTable 8: Filtering and Sorting PatternsTable 9: Content NegotiationTable 10: HTTP Caching HeadersTable 11: Conditional Requests and ETagsTable 12: Authentication and Authorization PatternsTable 13: OWASP API Security Top 10 (2023)Table 14: API Versioning StrategiesTable 15: HATEOAS and Hypermedia FormatsTable 16: Rate Limiting and ThrottlingTable 17: CORS (Cross-Origin Resource Sharing)Table 18: Bulk Operations and Batch RequestsTable 19: Asynchronous and Long-Running OperationsTable 20: Webhooks and Event-Driven PatternsTable 21: API Deprecation and SunsetTable 22: Idempotency KeysTable 23: Field Selection and Sparse FieldsetsTable 24: OpenAPI Specification Best PracticesTable 25: API Documentation Best PracticesTable 26: API Governance Best PracticesTable 27: Designing for AI Agent ConsumersTable 28: Performance OptimizationTable 29: API Observability and MonitoringTable 30: API Testing StrategiesTable 31: API Gateway PatternsTable 32: Statelessness and Session ManagementTable 33: Common API Design Anti-Patterns

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

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-Server	`Client: Mobile app` `Server: API backend`	• Separation of concerns between user interface and data storage • clients and servers evolve independently without tight coupling.
Stateless	`Authorization: Bearer <token>`	• Each request contains all necessary context (auth, params) • server stores no session state between requests, improving scalability and reliability.
Cacheable	`Cache-Control: max-age=3600` `ETag: "abc123"`	• Responses explicitly labeled cacheable or not • reduces server load and latency by allowing clients and intermediaries to reuse responses.
Uniform Interface	`GET /users/123` `Accept: application/json`	• Standardized interaction via URIs, HTTP methods, and representations • simplifies architecture and improves visibility of interactions.
Layered System	Load balancer → API gateway → services	• Clients cannot tell whether connected directly to end server or intermediary • enables load balancing, caching, security layers.
Code on Demand (optional)	Server returns executable JS code	• Server temporarily extends client functionality by transferring executable code • the only optional constraint — rarely used in practice.

Table 2: Richardson Maturity Model Levels

The Richardson Maturity Model describes four levels of REST adoption, from plain HTTP transport (Level 0) to full HATEOAS (Level 3). Most production APIs operate at Level 2; Level 3 remains aspirational for most teams but is worth understanding as the true REST ideal.

Level	Example	Description
Level 2 — HTTP Verbs	`GET /users/123` `DELETE /users/123`	• Proper HTTP methods (GET, POST, PUT, DELETE) with appropriate status codes • the practical sweet spot — the level most production APIs target.

The rest of this section is part of the full cheat sheet

Table 3: HTTP Methods and Idempotency Guarantees

HTTP methods carry precise semantic and idempotency guarantees that caches, proxies, and clients all rely on. Breaking these contracts — such as making GET requests that mutate state — silently corrupts caching and retry logic throughout the stack.

Method	Example	Description
GET	`GET /users/123`	• Retrieve resource • safe and idempotent — multiple identical requests return same result without side effects.

The rest of this section is part of the full cheat sheet

Table 4: Resource Naming Conventions

Consistent, noun-first URL patterns make API surfaces predictable and self-describing. Deviating from established conventions — mixing verbs in paths, inconsistent plural/singular, or exposing file extensions — forces clients to learn non-standard dialects per endpoint.

Convention	Example	Description
Use nouns, not verbs	`GET /users` not `/getUsers`	• Resources represent entities (nouns) • HTTP methods provide verbs — mixing verbs in URLs violates REST principles.

The rest of this section is part of the full cheat sheet

Table 1: REST Architectural Constraints

Constraint	Example	Description
Client-Server	`Client: Mobile app` `Server: API backend`	• Separation of concerns between user interface and data storage • clients and servers evolve independently without tight coupling.
Stateless	`Authorization: Bearer <token>`	• Each request contains all necessary context (auth, params) • server stores no session state between requests, improving scalability and reliability.
Cacheable	`Cache-Control: max-age=3600` `ETag: "abc123"`	• Responses explicitly labeled cacheable or not • reduces server load and latency by allowing clients and intermediaries to reuse responses.
Uniform Interface	`GET /users/123` `Accept: application/json`	• Standardized interaction via URIs, HTTP methods, and representations • simplifies architecture and improves visibility of interactions.
Layered System	Load balancer → API gateway → services	• Clients cannot tell whether connected directly to end server or intermediary • enables load balancing, caching, security layers.
Code on Demand (optional)	Server returns executable JS code	• Server temporarily extends client functionality by transferring executable code • the only optional constraint — rarely used in practice.

Table 2: Richardson Maturity Model Levels

Level	Example	Description
Level 2 — HTTP Verbs	`GET /users/123` `DELETE /users/123`	• Proper HTTP methods (GET, POST, PUT, DELETE) with appropriate status codes • the practical sweet spot — the level most production APIs target.

Table 3: HTTP Methods and Idempotency Guarantees

Method	Example	Description
GET	`GET /users/123`	• Retrieve resource • safe and idempotent — multiple identical requests return same result without side effects.

Table 4: Resource Naming Conventions

Convention	Example	Description
Use nouns, not verbs	`GET /users` not `/getUsers`	• Resources represent entities (nouns) • HTTP methods provide verbs — mixing verbs in URLs violates REST principles.