What Is API Design?

Summary#

An API is a contract between two systems. It says: “If you send me bytes shaped like this, I will send you back bytes shaped like that, and the side-effects will be those.” The shape of the bytes, the semantics of the operation, the error taxonomy, the rate-limit policy, the versioning scheme — every word of that is part of the contract.

API design is the discipline of writing that contract well. Good API design is what makes Stripe a verb, what makes AWS the default for new infrastructure, what makes the GitHub REST API a thirteen-year-old artefact that still ships unchanged endpoints. Bad API design is what makes engineers write 200 lines of glue code to call your service, what makes your on-call wake up at 3am because a client retried a non-idempotent POST, what makes your v2 a backwards-incompatible rewrite instead of an additive extension.

API design is distinct from system design. System design is about storage, replication, sharding, fault tolerance — the machinery behind the contract. API design is about the contract itself: what the caller sees. The two are connected (a poorly-designed contract can force the implementation into bad trade-offs) but the disciplines are separate. A senior system designer who has never sweated the shape of a public-facing API will produce internal services that ship and external APIs that age badly.

Why it matters#

Three concrete reasons companies care about API design as a first-class discipline:

• The API is the product surface. For Stripe, Twilio, AWS, Google Maps, OpenAI, the API is the product. The developer experience of integrating it is the competitive bar. A clear, consistent, well-documented API beats a more capable but harder-to-use one in 80% of evaluation cycles.
• The API ages slower than the implementation. You will rewrite the service behind your /users endpoint three times in ten years. The endpoint itself, if designed well, will stay. Bad API design ages you into v2 / v3 / v4 endpoints (each duplicating the previous), into deprecation timelines that never end, into client libraries that have to maintain three code paths.
• The API is the contract with everyone who isn’t you. Internal callers can be coordinated. Mobile clients shipped six months ago cannot. Partner integrations cannot. The third-party CLI someone wrote on the weekend cannot. Every breaking change you make becomes a coordination problem with the universe. Good API design is the discipline that minimises how often you have to ask the universe to update.

For an engineering interview, the API-design round tests a different skill from the system-design round. The interviewer is watching whether you can think about the consumer of the API — the developer who will integrate it next month — not just about the bytes that flow.

How it works#

An API contract has six parts. Every API-design exercise — interview or production — is some refinement of these six.

1. The actors#

Who calls this API? A browser? A mobile app? A partner backend? An internal microservice? A third-party integration? The audience shapes everything:

• Public partner API → REST is the default. Self-describing, browser-friendly, cacheable.
• Internal polyglot mesh → gRPC with Protobuf. Strongly-typed, code-generated clients in every language.
• Mobile / data-flexible web → GraphQL. One endpoint, client-shaped responses.
• Real-time bidirectional → WebSockets or SSE.

You cannot design the contract without knowing the consumer. Half of bad API design traces to a contract optimised for the wrong audience.

2. The operations#

What can the caller do? In REST, the answer is a small set of verbs (GET, POST, PUT, PATCH, DELETE) over a set of resources. In RPC, the answer is named methods (CreateUser, ShipOrder, RefundCharge). In GraphQL, the answer is queries and mutations.

In every style, the discipline is to name the operation at the level the caller cares about. POST /orders is a sale, not a row insert. RefundCharge is a business outcome, not three database updates. The name leaks the abstraction every time the implementation changes.

3. The data#

What goes in? What comes back? In <Tabs> form across Python, Go, and Node — your callers will integrate from at least three language ecosystems. JSON is the default for everything that touches the public Internet; Protobuf for internal high-throughput services; OpenAPI YAML to formally document the schema.

{
  "id": "ord_a3f9c2",
  "status": "confirmed",
  "amount": { "currency": "USD", "value_minor": 4999 },
  "items": [
    { "sku": "SKU-X42", "qty": 1, "name": "Wireless mouse" }
  ],
  "created_at": "2026-05-30T08:14:23Z"
}

4. The constraints#

What’s the rate limit? What’s the maximum payload size? What’s the timeout? Is the operation idempotent? Are partial successes possible? Constraints are part of the contract — undocumented constraints are bugs waiting to surprise you.

5. The errors#

When things go wrong, what does the caller see? A consistent error envelope ({ "error": { "code": "...", "message": "...", "request_id": "..." } }) plus a stable error-code vocabulary is worth more to integrators than any individual feature. The Stripe error model is a textbook example.

6. The evolution#

How does this contract change without breaking callers? Additive changes (new optional fields, new endpoints) are free. Breaking changes (removed fields, changed semantics, renamed endpoints) require versioning, deprecation timelines, and migration guides. A good API design picks an evolution model on day one and sticks to it.

Variants and trade-offs#

Different API contexts emphasise different parts of the six:

When this is asked in interviews#

The first question in an API-design interview is almost always “design the X API.” The interviewer is testing five things in roughly this order:

• Do you clarify the consumer first? A surprising number of candidates start enumerating endpoints before asking who’s calling. The answer to “browser vs mobile vs partner backend” changes everything.
• Do you name operations at the business level? POST /orders is good; INSERT INTO orders is a code smell.
• Do you nominate a style with reasons? REST vs GraphQL vs gRPC is a choice; the right answer depends on the consumer, the latency budget, and the team’s polyglot needs.
• Do you have an evolution story? “What does v2 look like?” is the second-most-common follow-up. The first is “what happens if the call times out?”
• Do you treat error semantics as first-class? Most candidates wave hands at “we return 500s”. The senior signal is naming the error vocabulary and showing how the client distinguishes a retryable error from a permanent one.

The strongest summary you can leave the interviewer with: “I designed for the integrator, not for the implementation.” That sentence is the difference between API design and system design.

Related concepts#

• Business Considerations of APIs — APIs as products. Monetisation, developer experience, the Stripe playbook.
• The Narrow Waist of the Internet — the IP-and-HTTP substrate every API stands on.
• Latency and Throughput — the two dimensions every API contract must respect.
• Web API Architectural Styles — Overview — REST, GraphQL, gRPC, and where each one fits.
• The API-Design Walk-through — the repeatable seven-step recipe for an API-design interview round.