APIs and protocols
How systems talk to each other — contracts across a boundary, and the rules that carry them.
- Define an API as a contract across a boundary between systems
- Distinguish synchronous request/response from asynchronous messaging
- Explain why versioning, errors, and idempotency matter
An API (Application Programming Interface) is the same idea as an interface from earlier, applied across the boundary between separate systems: a published contract that lets one program use another without knowing its internals. A protocol is the agreed set of rules for how they exchange those messages. Together they're how the software world is wired up.
Contracts across a boundary
When your app asks a payments service to charge a card, it relies on a contract: send a request shaped like this, get back a response shaped like that. Neither side sees the other's code. As long as both honour the contract, each can change internally and evolve independently — abstraction at the scale of whole systems.
Synchronous vs asynchronous
Two fundamental shapes of communication:
- Request/response (synchronous): you ask and wait for an answer, like a phone call. Simple to reason about; the caller is blocked until the reply arrives (and must handle it never arriving).
- Messaging/events (asynchronous): you send a message and move on, like email; the work happens later, and you're notified when it's done. Better for slow work and decoupling, at the cost of more complexity in tracking outcomes.
Choosing between them is an architectural decision: do callers need the answer now, or can the work happen in the background?
The things that bite across boundaries
Inside one program, calls are reliable. Across systems, the network is not — and that changes what you must design for:
- Errors and retries. Requests fail, time out, or arrive twice. The contract must say what an error looks like, and callers must handle it.
- Idempotency. If a "charge the card" request might be retried, sending it twice must not charge twice. An idempotent operation is safe to repeat — crucial when the network is unreliable.
- Versioning. Other people depend on your API's shape. Change it carelessly and you break them; hence versioning and backwards compatibility, so old callers keep working while new ones get new features.
The hardest API bugs come from forgetting the network is unreliable. Always ask: what happens if this request fails, is slow, or arrives twice?
Where to go next
APIs let many things happen at once — which raises a hard question we've been circling: concurrency, doing more than one thing at a time.