API Design¶
Tier: 2 (Architectural Judgment)
Concepts: 14
Durability: Durable (Core principles predate and transcend REST/GraphQL/RPC; rooted in interface design theory and distributed systems constraints)
Fundamental Tensions¶
| Tension | Description |
|---|---|
| Flexibility vs. Simplicity | Flexible APIs (client-specified queries, nested resources) increase complexity for both provider and consumer. Simple APIs may require multiple round-trips or overfetch. Neither extreme optimizes both learning curve and power. |
| Stability vs. Evolution | Consumers depend on stable contracts; providers need to evolve capabilities. Perfect backward compatibility prevents necessary change; frequent breaking changes destroy trust. Versioning strategies manage but cannot eliminate this tension. |
| Generality vs. Usability | Generic APIs serve many use cases but optimize none; tailored APIs fit specific needs but proliferate endpoints. The "one-size-fits-all" API is a myth - every design chooses a point on this spectrum. |
| Convenience vs. Performance | Convenient APIs (rich nested responses, computed fields) shift work to the server; performant APIs (minimal responses, explicit fetching) shift work to the client. Network latency, compute costs, and developer experience trade against each other. |
| Discoverability vs. Coupling | Self-describing APIs (HATEOAS, introspection) enable runtime discovery but couple clients to response structure; documented-only APIs reduce runtime coupling but require out-of-band knowledge. |
Concepts¶
- Resource as Primary Abstraction
- Statelessness as Scalability Enabler
- Idempotency as Reliability Foundation
- Contract-First Design
- Postel's Law (Robustness Principle)
- Versioning as Change Management
- Uniform Interface Principle
- Error Design as First-Class Concern
- Pagination as Bounded Response Pattern
- Rate Limiting as Resource Protection
- Hypermedia as Engine of Application State (HATEOAS)
- Query Flexibility vs. Server Optimization Trade-off
- Backward Compatibility as Trust Contract
- Richardson Maturity Model as Capability Spectrum
Cross-Domain Transfer Summary¶
| This Domain Concept | Transfers To |
|---|---|
| Resource as Primary Abstraction | Database design, DDD, File systems, OOP |
| Statelessness | Distributed systems, Functional programming, Load balancing, Caching |
| Idempotency | Distributed systems, Message queues, Database operations, FP |
| Contract-First Design | TDD, Protocol design, Schema design, Type systems |
| Postel's Law | Protocol design, Parsers, Data migration, Microservices |
| Versioning | Package management, Database migrations, Library design |
| Uniform Interface | File system APIs, Database interfaces, Unix philosophy |
| Error Design | Exception design, Compiler messages, UI error states |
| Pagination | Database queries, Directory listings, Search results |
| Rate Limiting | OS resource limits, Connection pools, Circuit breakers |
| HATEOAS | Web navigation, Workflow engines, State machines |
| Query Flexibility Trade-off | Database languages, Report builders, Search interfaces |
| Backward Compatibility | Library versioning, OS APIs, Hardware interfaces |
| Maturity Models | Capability maturity models, Adoption curves |
Canonical Sources¶
| Source | Coverage |
|---|---|
| Fielding, "Architectural Styles and the Design of Network-based Software Architectures" (2000) | REST foundations, statelessness, uniform interface, HATEOAS |
| Richardson & Ruby, "RESTful Web Services" (2007) | Resource-oriented design, practical REST patterns |
| Masse, "REST API Design Rulebook" (2011) | Error design, versioning, practical guidelines |
| Geewax, "API Design Patterns" (2021) | Modern patterns, pagination, field selection |
| Kleppmann, "Designing Data-Intensive Applications" (2017) | Idempotency, distributed systems context |
| Nygard, "Release It!" (2007, 2018) | Rate limiting, stability patterns |
| Bloch, "Effective Java" (2001, 2008, 2018) | API design principles, backward compatibility |
| Postel, RFC 761 (1980) | Robustness principle |
| HTTP RFCs (7230-7235, 7807) | Protocol semantics, error formats |
| Fowler, "Richardson Maturity Model" (2010) | REST adoption levels |
| GraphQL Specification (2015) | Alternative API style, query flexibility |