Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
3.0 KiB
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
- Contract Fidelity — never sacrificed.
- Security — never sacrificed.
- Stability — sacrificed only with a documented deprecation cycle.
- Clarity — sacrificed only for Performance with evidence.
- Predictability — sacrificed for Composability when patterns diverge.
- Composability — sacrificed for Clarity when abstractions confuse.
- Idempotency — sacrificed only for genuinely non-idempotent operations.
- Performance — sacrificed only with measurement.
- Error Transparency — sacrificed only for security-sensitive errors.
- 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.