API Design & Service Communication

Every system design interview eventually reaches the sentence "and the client calls the service to…". What happens next — which verbs, which payloads, which transport, what happens on retry — is where a candidate either sounds like someone who has shipped APIs or someone who has only drawn boxes. The API is the contract between teams and between the present and future versions of a system; get it wrong and every consumer pays for years.

This subject covers the practical decisions: how to shape REST resources and errors, how to paginate a billion-row table without falling over, how to make "charge the card" safe to retry, when gRPC or GraphQL beat REST, how to push data to clients in real time, and how services should talk to each other (gateways, auth, discovery, deadlines). It closes with a worked API for a ride-hailing trip lifecycle and the traps interviewers set.

Sibling boundaries: rate-limiting algorithms are covered in the Rate Limiting subject; retries, circuit breakers and timeouts are covered in depth in the Reliability & Observability Patterns subject; async messaging internals are covered in the Message Queues & Event Streaming subject. Here we cover only the API-facing side of each.