API, contract, and interface architecture
An interface is a behavioral promise across an ownership boundary. Good API architecture includes semantics, identity, authorization, compatibility, failure, idempotency, quotas, observability, and lifecycle.
Core ideas and patterns
| Idea | What it solves | Cost, limit, or warning |
|---|---|---|
| REST | Models resources over standard HTTP semantics | Poor resource modeling becomes RPC with URLs |
| RPC/gRPC | Provides typed efficient operation calls | Tighter client/server coupling and proxies need management |
| GraphQL | Lets clients select a composed graph | Cost, authorization, caching, and N+1 need controls |
| Webhook | Pushes change to external consumers | Delivery security, retries, ordering, and replay are hard |
| Async API | Defines message channels and event contracts | Consumer behavior is less immediately visible |
| Backend for frontend | Shapes APIs for a specific client experience | Duplicated policy across BFFs is a risk |
| API composition | Aggregates several services for one use case | Latency and failure multiply |
| Pagination/cursor | Bounds large result retrieval | Mutable datasets require stable ordering semantics |
| Idempotency key | Makes retried commands safe | Scope, collision, response replay, and expiry need definition |
How to apply it
Design from consumer tasks and domain language. Define success and every failure state, authorization at resource/action level, concurrency control, idempotency, pagination, rate policy, and version compatibility. Avoid leaking database structures. Publish examples and machine-readable contracts.
Evidence, not opinion
Run schema linting, consumer-driven contracts, backward-compatibility checks, authorization matrix tests, fuzz/property tests, quota tests, and synthetic probes. Track deprecation consumers and removal dates.
Small example
POST /transfers accepts an idempotency key and expected account version. A timeout can be retried safely; a version conflict returns a stable problem document instead of silently overwriting.
Feynman check
Explain the design to a new engineer without using the pattern names. State the problem, the forces that conflict, the chosen boundary or mechanism, what can fail, and the evidence that would prove the choice still works.