architecture-descriptionestablished · low operational burden

API Design Principles

Also known as: api-principles, rest-principles, design-principles, api-guidelines

Intent

Foundational principles for designing consistent, evolvable, developer-friendly APIs — beyond syntax to architecture.

Problem

APIs grow organically: inconsistent naming, breaking changes, poor discoverability. Principles prevent debt.

Forces

•Multiple teams designing APIs independently
•Consumers: web, mobile, partners — different needs
•Evolution: add fields, deprecate, version
•Standards: HTTP semantics, JSON, RFCs

Solution

✓ When to Use

•Any team building APIs
•Multiple teams, multiple consumers
•Public or partner APIs

✗ When Not to Use

•Internal RPC (gRPC better)
•Throwaway prototypes

Pros

+Predictable, learnable, maintainable APIs
+Reduced coordination: teams work independently
+Faster onboarding: consistent patterns
+Safer evolution: breaking changes caught

Cons

−Process overhead: review, linting, governance
−Initial slowdown: design before code
−Flexibility trade-off: consistency constrains

Cost Profile

Infrastructure

Low — design discipline, linting

Operational

Low — version management

Cognitive

Medium — conventions, trade-offs

Failure Modes

Governance theater: rules exist, not enforced
Over-standardization: stifles innovation
Version explosion: 20 versions maintained
Documentation drift: spec ≠ implementation

Real-World Examples

Alternatives

graphql
grpc
tRPC
rpc
no-guidelines

Related Patterns

api-design
api-versioning
api-gateway
consumer-driven-contracts
openapi
pagination
idempotency-key

Competency Domains

distribution communicationeconomics evolutiondeploymentreliability opssecurity compliance