API and Contract Design

Design APIs that remain stable under scale, retries, versioning, and independent client releases.

25 min

3 sections

api

contracts

versioning

01. Model workflows, not database tables

Section 1 of 3

Production APIs should expose product actions and stable contracts, not internal table shapes. A checkout API should talk about carts, reservations, payment attempts, and order confirmation, not directly expose inventory rows.

json

POST /v1/carts/{cartId}/reserve
Idempotency-Key: 01J-system-design-example

{
  "items": [
    { "sku": "SKU-123", "quantity": 2 }
  ],
  "expiresInSeconds": 900
}

Response 201:
{
  "reservationId": "res_123",
  "expiresAt": "2026-07-05T15:15:00Z",
  "status": "HELD"
}

Capacity Estimation and Bottlenecks

Data Modeling for System Design

Back to Course