atelier/domains/api/first-principles.md

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.