Jon Chery
84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# API Design — First Principles
|
|
|
|
**Version:** 1.0.0
|
|
**Status:** Foundational
|
|
**Audience:** AI agents and humans designing APIs (REST, GraphQL,
|
|
gRPC, RPC, libraries).
|
|
|
|
## 1. Manifesto
|
|
|
|
An API is a contract between systems and the people who build on
|
|
them. The cost of an API is paid by every consumer, forever. The
|
|
highest quality API is one that a stranger can use correctly without
|
|
reading the source.
|
|
|
|
## 2. The Principles
|
|
|
|
### P1. Contract Fidelity
|
|
The API does what its documentation says, and the documentation says
|
|
what the API does. Nothing more, nothing less.
|
|
|
|
### P2. Clarity
|
|
Endpoints, methods, parameters, and responses are named and structured
|
|
for the consumer — not for the implementer.
|
|
|
|
### P3. Predictability
|
|
Consumers can guess behavior without reading docs. Patterns repeat.
|
|
Surprises are bugs.
|
|
|
|
### P4. Composability
|
|
Resources and operations combine cleanly. The whole is greater than
|
|
the sum of its parts, and the parts are reusable in new wholes.
|
|
|
|
### P5. Versioning
|
|
Changes are managed explicitly, not implicitly. Consumers know what
|
|
will break, and when.
|
|
|
|
### P6. Idempotency
|
|
Repeated identical calls have the same effect as a single call. Retry
|
|
is a first-class operation.
|
|
|
|
### P7. Performance
|
|
Latency, payload size, and call count are designed in — not optimized
|
|
out.
|
|
|
|
### P8. Security
|
|
Authentication, authorization, validation, and rate limiting are
|
|
defaults, not add-ons.
|
|
|
|
### P9. Error Transparency
|
|
Failures are communicated specifically, structurally, and actionably.
|
|
|
|
### P10. Stability
|
|
Consumers can build on the API without fear of breakage. Backward
|
|
compatibility is a default.
|
|
|
|
## 3. Conflict Resolution
|
|
|
|
1. Contract Fidelity — never sacrificed.
|
|
2. Security — never sacrificed.
|
|
3. Stability — sacrificed only with a documented deprecation cycle.
|
|
4. Clarity — sacrificed only for Performance with evidence.
|
|
5. Predictability — sacrificed for Composability when patterns diverge.
|
|
6. Composability — sacrificed for Clarity when abstractions confuse.
|
|
7. Idempotency — sacrificed only for genuinely non-idempotent operations.
|
|
8. Performance — sacrificed only with measurement.
|
|
9. Error Transparency — sacrificed only for security-sensitive errors.
|
|
10. Versioning — never sacrificed (always have a version policy).
|
|
|
|
## 4. What Violates These Principles
|
|
|
|
| Violation | Principle Breached |
|
|
|------------------------------------|----------------------|
|
|
| Endpoint name exposes DB schema | P2 Clarity |
|
|
| Breaking change without deprecation | P10 Stability |
|
|
| Generic 500 with stack trace | P9 Error Transparency|
|
|
| Auth as opt-in | P8 Security |
|
|
| Non-idempotent POST without key | P6 Idempotency |
|
|
| Inconsistent naming across endpoints | P3 Predictability |
|
|
| Required response field undocumented | P1 Contract Fidelity |
|
|
| 10MB response payload by default | P7 Performance |
|
|
|
|
## 5. Relationship to Core
|
|
|
|
Subordinate to `core/first-principles.md`. See `matrix/principles-matrix.md`. |