Section 4: The Contract That Survives a Refresh - API Design

Executive Summary: Section 3 proved the asymmetry — 28 booking writes per second at chain peak against 25.8 million cell reads per second — so this API's job was never throughput. Its job is making the rare write safe for a human who refreshes, hunts for a credit card, and double-clicks Confirm. Four endpoints carry the product: a date-keyed availability read, a POST /v1/holds that leases inventory for ten minutes, a POST /v1/bookings guarded by a client-minted idempotency key, and the retrieval surface. Two decisions deserve defending under fire — why the hold is a separate call, and why idempotency comes from a key rather than from a verb.

The interviewer stops writing numbers and asks the practical question: "Fine. Show me the API." Most candidates answer by listing resources — hotels, rooms, reservations — and that instinct smuggles in Section 1's Seat-Map Reflex. What you sell is not a room; it is a lease on a counter for a contiguous run of dates, and the interface should say so out loud.

Four Endpoints, and the Reason There Are Not Fourteen

Start with the read, and notice the parameters are dates, not nights.

GET /v1/availability?property_id=marlin-bay-miami
    &check_in=2026-03-13&check_out=2026-03-16&adults=2

{
  "nights": ["2026-03-13", "2026-03-14", "2026-03-15"],
  "room_types": [
    { "room_type_id": "ocean-view-suite", "available": 1,
      "available_basis": "min across the 3 requested nights",
      "rate_plan_id": "FLEX-REF", "nightly_rate": 420,
      "total_before_tax": 1260, "currency": "USD" }
  ]
}

The server derives the three nights and echoes them back. That echo makes Section 1's off-by-one impossible to get wrong at the boundary: Dana checking out on 03-16 consumes no inventory on 03-16, and every consumer — your web app, Expedia, a travel agent's GDS terminal — reads that interpretation instead of inferring it. And available is the minimum across those nights rather than a per-night figure: one suite left on the Saturday caps the whole stay at one, however open the Friday is.

Then the lease, then the commit.

POST /v1/holds
{ "property_id": "marlin-bay-miami", "room_type_id": "ocean-view-suite",
  "rate_plan_id": "FLEX-REF", "check_in": "2026-03-13",
  "check_out": "2026-03-16", "guests": { "adults": 2 } }

201 Created
{ "hold_id": "hld_4b81", "expires_at": "2026-03-01T23:34:00Z",
  "nightly_rate": 420, "total_before_tax": 1260 }

409 Conflict
{ "error": "sold_out",
  "alternatives": [ { "room_type_id": "double-queen", "nightly_rate": 260 } ] }

POST /v1/bookings
Idempotency-Key: bk_9f3c71a2
{ "hold_id": "hld_4b81", "guest": { "name": "Dana Reyes" },
  "payment_method_token": "pm_tok_8812" }

201 Created
{ "confirmation_number": "MBM-7K4P2Q", "status": "confirmed",
  "total_before_tax": 1260 }

The Double Queen in that 409 body is priced in season; the property's $250 ADR is the annualised blend across all four room types and both seasons, which is why $260 and a $420 suite both sit above it.

The rest is retrieval: GET /v1/bookings/MBM-7K4P2Q, PATCH to move the dates, DELETE to cancel — which returns the refund the rate plan computes, not a bare 204, because "we cancelled it" and "we are keeping one night under FLEX-REF" are different facts and a guest is owed both.

Capture is not in this call: the post-commit outbox carries it, and under FLEX-REF it fires at check-in (Section 6).

Quick check before moving on: