Why API Design

Why this course exists

API design shows up in two very different interview contexts. In a System Design round, the interviewer usually wants a one-minute answer: REST as default, mention gRPC for internal services, GraphQL when the client needs flexible reads — then move on to databases, caching, and scaling. In a backend or platform round, or when the prompt is explicitly “design a REST API for X,” they expect you to stay on APIs: resource modeling, HTTP semantics, error shapes, pagination, idempotency, and when to break REST-ish conventions on purpose.

Knowing which mode you are in saves time. If the whiteboard says “design Twitter,” do not spend fifteen minutes debating cursor pagination. If the prompt says “design the checkout API,” do not hand-wave with “we’ll use REST” and jump to Kafka.

For the short HLD pass — when to default to REST, when gRPC or GraphQL earns a mention, and how APIs fit next to databases and queues — read API Design in System Design. That chapter is the breadth view. This course is the depth view.

What happens on the wire (and why it matters)

An API is not just JSON shapes. Every request is bytes over TCP, often wrapped in TLS, routed through load balancers and gateways, possibly retried by a client library you never wrote. You do not need to be a networking expert to design a good API, but you should know where your contract ends and the transport begins.

Status codes exist so clients can classify outcomes without parsing the body. Timeouts and retries mean idempotency is not academic — a duplicate POST after a gateway timeout can double-charge a customer. Stateless servers scale horizontally because any instance can serve any request if the message carries enough context.

If packets, TLS, and the request/response lifecycle feel fuzzy, skim Networking overview first. You can take this course without it, but the HTTP chapters land harder when you know what actually crosses the network.

When interviews dig in vs when to move on

Dig in when:

• The role is API-heavy (platform, payments, developer experience, BFF).
• The prompt names endpoints, clients, or versioning explicitly.
• The interviewer asks follow-ups: “What status code?”, “How do you page this?”, “What if the client retries?”
• You proposed GraphQL or gRPC and they want trade-offs, not buzzwords.

Move on when:

• The system design is dominated by data modeling, replication, or fan-out (feed, metrics, search).
• You already stated REST + JSON and the interviewer nodded toward storage or sharding.
• Time is short and API choice is not the differentiator for the problem.

A strong candidate signals awareness in system design (“REST for public CRUD, idempotency keys on payment POSTs”) and can go deep when the interview turns that direction.

What this course covers

The course walks REST as an architectural style, not “JSON over HTTP,” then covers the HTTP details interviewers actually ask about.

Foundations and REST

• The six constraints Fielding defined, and what “REST-ish” means in production JSON APIs
• Resources, URIs, representations, and naming conventions (nouns, plurals, nesting depth)
• HTTP methods, safety, idempotency, and why retries make semantics matter
• Statelessness: what belongs in the message vs what must not live in server RAM

HTTP practicals

• Status codes: 2xx, 4xx, 5xx mapping; 401 vs 403; when 409 and 422 earn their keep
• Error bodies and Problem Details (application/problem+json, RFC 7807)
• Versioning (URL vs header vs additive-only), pagination (offset vs cursor), filtering, sorting
• Idempotency keys for non-idempotent POSTs (payments, creates)

Styles beyond REST

• gRPC: protobuf contracts, HTTP/2, streaming, deadlines, grpc-web
• GraphQL: schema, queries/mutations/subscriptions, N+1, caching, complexity limits
• A decision framework: REST vs RPC vs GraphQL by client, caching, team workflow, network constraints

Wrap-up

• Common misconceptions (“REST = JSON”, “always POST”)
• Interview Q&A you can rehearse out loud

How this course is organized

Read in order if REST semantics are rusty. If you already ship APIs daily, skim REST Constraints and Status Codes & Errors, then jump to REST vs RPC vs GraphQL and Interview Questions.

What interviewers reward

Strong answers share traits:

• Name resources before endpoints — “The resource is an order; the collection is /orders” beats jumping to JSON field names.
• HTTP semantics, not habits — 201 on create, 409 on conflict, 401 vs 403 correct, no 200-with-error-body.
• Operational awareness — retries imply idempotency; large lists imply cursor pagination; public APIs imply versioning policy.
• Honest trade-offs — “REST here for CDN cacheable GETs; gRPC internally for order fulfillment streaming” shows judgment.

Weak answers over-index on tools (“we’ll use GraphQL”) without naming clients, caching, or auth. Weak answers treat REST as synonymous with JSON. This course targets the strong pattern.

What this course does not cover

Auth flows (OAuth2, mTLS), webhook design, rate-limit implementation, and OpenAPI authoring mechanics are adjacent topics. System Design covers where APIs sit in larger architectures — System Design track — including databases, queues, and replication. Networking covers TLS, DNS, and load balancing — Networking track.

Stay in this course when the interviewer’s follow-ups stay on resources, HTTP, and API style choice.

How to use this course

The goal is not to memorize RFCs. The goal is to design and defend an API in forty-five minutes: name resources, pick verbs, return the right status, page a large collection safely, and explain why you did not reach for GraphQL on a public CRUD surface.

Work through each chapter’s Interview framing section by closing the tab and answering aloud. The wrap-up chapter is a full rehearsal list.