---
title: "API, contract, and interface architecture"
chapter: "18"
---

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