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`.