Section 4: A Hold Is a Thing, Not a Lock - API Design (with Pushback)

Executive Summary: This section writes the public contract: event and seat-map reads that live at the edge, a queue that hands out signed tokens, a hold that is a resource with its own id and expiry, a checkout guarded by an idempotency key, and a ticket endpoint that serves rotating barcodes. The layout is cached for the whole show; availability is a 7.5 KB bitmap polled every 2 seconds. Then the interviewer pushes on four choices: why a hold is a resource and not a lock call, why best-available runs on the server, why checkout needs its own idempotency key, and why a lost race returns 409 with alternatives instead of a bare error.

Section 3 ended with the uncomfortable numbers: 20,000 admitted shoppers making about 20,000 requests a second, behind three million fans who must never reach the origin. The interviewer slides the marker across. "Good. Now the API."

The weak answer is POST /book {seatId, card}: one call with no notion of time, no safe retry, and a charge before the seats are known to be yours. The Staff answer separates the steps, because each one has a different consistency need and a different place it can be served from:

GET    /v1/events/{eventId}                     event page (CDN)
GET    /v1/shows/{showId}/seatmap               static layout for the show (CDN)
GET    /v1/shows/{showId}/availability          7.5 KB bitmap, ETag, poll every 2 s
POST   /v1/shows/{showId}/queue                 join the waiting room, get a signed token
GET    /v1/queue/status                         position, ETA, admitted? (served at the edge)
POST   /v1/shows/{showId}/holds                 hold specific seats or best-available
DELETE /v1/holds/{holdId}                       release a hold early
POST   /v1/holds/{holdId}/checkout              pay for a hold
GET    /v1/orders/{orderId}                     order status
GET    /v1/orders/{orderId}/tickets             tickets with rotating barcode payloads

Reads: The Layout Once, Availability Every Two Seconds

A seat map is two different things glued together. The layout (sections, rows, seat coordinates, price zones, accessibility) is fixed for the show, so GET /seatmap is cacheable at the CDN for the life of the show. The availability changes up to 1,000 times a second during an on-sale, so it gets its own endpoint and its own shape: one bit per seat, 60,000 bits, 7.5 KB.

GET /v1/shows/E-7781/availability
If-None-Match: "v-918204"

200 OK
ETag: "v-918227"
{ "version": 918227, "bitmap": "<base64, 7.5 KB>" }

The client polls every 2 seconds and sends its ETag; if nothing changed, the answer is a 304 with no body. At 20,000 shoppers that is 10,000 requests a second and at most 75 MB/s, all from cache. Section 6 defends this bitmap against querying the database per view and against pushing every change to every client. The contract only needs to say one thing out loud: the served bitmap is at most 2 seconds behind the database, a fan's screen adds up to one more 2-second poll, and the hold is the truth.