API Design

How to design an HTTP API that clients can rely on for years: resources and methods, status codes and errors, pagination, safe retries, versioning, authentication and rate limits.

Overview

An API (application programming interface) is the contract between a service and the programs that call it: which requests exist, what they take, what they return, and how they fail. Once other teams or companies build on it, the contract is hard to change, because you cannot update their code for them.

That is why API design is mostly about the future. A good API is predictable (the same patterns everywhere), safe to retry, cheap to page through, clear when it fails, and able to grow without breaking the clients it already has.

This chapter is about designing HTTP APIs, the kind most system design interviews ask for. The choice between REST, RPC styles such as gRPC, and GraphQL has its own chapter, REST vs RPC; everything here applies whichever you pick.

What you will be able to do

  • Write clean endpoints for a product: resources, methods and status codes.
  • Return errors a client can act on, in a standard format.
  • Design list endpoints with cursor pagination that stays fast on deep pages.
  • Make create and payment calls safe to retry with idempotency keys.
  • Evolve an API without breaking clients, and retire old versions politely.

Key concepts

  • Resources and URLs
  • Methods and status codes
  • Error format
  • Cursor pagination
  • Idempotency keys
  • Versioning
  • Deprecation and sunset
  • OAuth 2.0 and API keys
  • Rate limits
  • API gateway

Interview questions

  • Design the API for an online store's orders.
  • PUT, PATCH or POST: which do you use, and why does it matter?
  • Why is offset pagination slow on deep pages, and what do you use instead?
  • How do you make a payment endpoint safe to retry?
  • How do you version an API, and how do you avoid needing to?
  • What should an error response contain?
  • API keys, OAuth 2.0 or JWTs: when do you use each?
  • What does an API gateway do, and what should it not do?

Sign up free to read the full topic

More System Design topics

Start free on Cariara · Coding problems · System design studio