Section 4: Five Verbs and a Signature - API Design (with pushback)
Executive Summary: The contract is REST over /{bucket}/{key}: five object verbs (PUT, GET, HEAD, DELETE, LIST) and four multipart calls, each authenticated by an HMAC signature over a canonical request (D8), with presigned URLs so browsers and phones move bytes without touching the customer's servers. The limits are the ledger's: objects to 5 TB, parts of 5 MB to 5 GB and at most 10,000 of them, keys up to 1,024 bytes, LIST pages of at most 1,000 keys, 2 KB of user metadata (N10). Errors are a vocabulary: 404 and 403 are kept apart on purpose, 412 carries conditional writes, and 503 Slow Down with Retry-After is how a partition's 3,500 writes/s budget (D9) reaches the client. Five pushbacks (HTTP over gRPC, the non-MD5 multipart ETag, no rename or append, the 1,000-key page, 503 instead of a queue) each trace back to a property the index and data layers must keep.
The interviewer caps the marker. "You have your numbers. Before you draw a box, tell me exactly what a customer calls. And each time you choose something, I will ask why not the other thing."
You: "A bucket, a key after it, and HTTP verbs meaning what they already mean. That is deliberate: Section 3 showed 5.6 Tbps of egress at peak, so the request body has to be a transport every CDN, browser, data lake and backup tool can already stream. Verbs first, then signing, then errors, because the error codes are where the promises become visible."
The Object Verbs
| Verb | Request essentials | Response | What it commits to |
|---|---|---|---|
PUT /{bucket}/{key} |
Content-Length, x-checksum-crc32c, x-meta-* (≤ 2 KB), optional If-None-Match: * |
200 + ETag |
Durable and visible on ack (D5); If-None-Match: * is create-if-absent, else 412 |
GET /{bucket}/{key} |
optional Range, If-None-Match |
200, 206 for a range, 304 on match |
Streams only the bytes asked for |
HEAD /{bucket}/{key} |
same conditionals | headers only | The cheap existence and metadata check |
DELETE /{bucket}/{key} |
none | 204, always |
Idempotent; a missing key is still 204 |
GET /{bucket}?list |
prefix, delimiter, max-keys ≤ 1,000, continuation-token |
keys, common prefixes, next token | Key-ordered; delimiter=/ folds "directories" at read time |
Priya's thumbnail is the small case, end to end:
PUT /lumen-thumbs/clip-00123/0001.jpg HTTP/1.1
Content-Length: 40960
Content-Type: image/jpeg
x-checksum-crc32c: 5zQ2kA==
Authorization: HMAC-SHA256 Credential=LUMEN7Q/20261031/blob,
SignedHeaders=host;x-date;x-checksum-crc32c, Signature=3b7d...
HTTP/1.1 200 OK
ETag: "9f1c0e4a2b..."
Forty kilobytes, one request, one ETag. The checksum header is the client's claim about the bytes; the front-end verifies it before acknowledging, the first link in the end-to-end chain Section 7 runs all the way to the disk. The ETag is the server's name for this exact content, so when the CDN later origin-pulls the thumbnail at high rate, If-None-Match gets a 304 and no bytes.
Sign in to continue reading
The rest of this lesson is available with a free account. Signing in with Google or Microsoft is free.
Sign in to read the full lesson