API Design

Pick a protocol, define your resources, decide how clients pass data and get responses back. This is the ~5-minute API step of the delivery framework — enough to look credible, then move on.

00 — FoundationWhat is an API?

Three components talk to each other through APIs: the client (your browser / laptop), the server (a machine in a data center), and the database (where data lives). For Ticketmaster, the browser makes an API call — "get me all the events" — the server receives it, makes its own query to the database, and passes the results back to the client.

01 — DecisionChoosing a protocol

You'll typically choose between three protocols. Their relative importance is very lopsided.

02 — The defaultREST

Resource modeling

Ticketmaster's core entities — events, venues, tickets, bookings — become REST resources:

GET    /events                 # all events
GET    /events/{id}            # one event
GET    /venues/{id}            # one venue
GET    /events/{id}/tickets    # tickets for an event
POST   /events/{id}/bookings   # create a booking
GET    /bookings/{id}          # one booking

Relationships: nesting vs. query params

HTTP methods & idempotency

Passing data to the API

Inputs come in three forms, each with a distinct role in the API's contract:

POST /events/123/bookings?notify=true
{
  "tickets": [
    {"section": "VIP", "quantity": 2},
    {"section": "General", "quantity": 1}
  ],
  "payment_method": "credit_card"
}

123 in the path (which event — required), notify=true as a query param (optional behavior), booking details in the body (the core data being created).

Returning data

A response has two parts: a status code (did it succeed?) and a response body (usually JSON).

03 — Flexible fetchingGraphQL

How it works

query {
  event(id: "123") {
    name
    date
    venue { name  address }
    tickets { section  price  available }
  }
}

The server returns exactly that — nothing more, nothing less. In REST this same data would need GET /events/123 plus GET /venues/{id} plus a tickets call. GraphQL folds it into one POST to a single endpoint.

Schema design

type Event {
  id: ID!
  name: String!
  date: DateTime!
  venue: Venue!
  tickets: [Ticket!]!
}
type Query {
  event(id: ID!): Event
  events(limit: Int, after: String): [Event!]!
}

Relationships are declared in the schema (an Event has a Venue), and clients traverse them in one query.

04 — Internal speedRPC & gRPC

// instead of  GET /events/123
getEvent(eventId: "123")

// instead of  POST /events/123/bookings
createBooking(eventId: "123", userId: "456", tickets: [...])

Protocol Buffers & type safety

service TicketService {
  rpc GetEvent(GetEventRequest) returns (Event);
  rpc CreateBooking(CreateBookingRequest) returns (Booking);
}
message GetEventRequest { string event_id = 1; }
message Event {
  string id = 1;  string name = 2;  int64 date = 3;
}

From one .proto file, gRPC auto-generates typed client and server code in many languages — so your Python service and your Java service talk with compile-time type safety, catching mismatches before deploy.

05 — The standardNine principles

You're rarely asked to recite these. They're the yardstick your design is judged against — and applying one out loud is how you sound like someone who has built real APIs.

06 — In productionCommon patterns

These show up regardless of protocol. In an interview, follow-ups almost always target pagination or security.

Pagination

Idempotency keys

POST /events/123/bookings
Idempotency-Key: 8e03978e-740c-4c2e-abd1-52f427d5c177
{ "tickets": [{ "section": "VIP", "quantity": 2 }] }

Filtering, sorting & consistent errors

Filter and sort with query params: /events?city=NYC&status=upcoming, /events?sort=-date (leading minus = descending). The work isn't inventing params — it's keeping them consistent across endpoints (if events filter by status, bookings shouldn't use state).

{
  "error": {
    "code": "SEAT_UNAVAILABLE",
    "message": "Section VIP has only 1 seat remaining"
  }
}

The code is a stable string client code branches on; the message is for humans and can change freely. Keep the shape identical everywhere so consumers write error handling once.

Versioning

07 — Set yourself apartSecurity

API keys vs. JWT

RBAC & rate limiting

Recall check — test yourself

08 — Scan before the interviewQuick revision

Primary source: “API Design for System Design Interviews,” Hello Interview · System Design in a Hurry. Instructor-insight annotations drawn from the companion lecture by Evan (former Staff Engineer at Meta, co-founder of Hello Interview). Notes reorganize and condense the material for study and recall; code examples are reproduced from the source.