Section 4: Two Customers, Three Contracts - API Design (with Pushback)
Executive Summary: Section 3, Scale Estimation, showed 150,000 publishes a second in and 600,000 deliveries out. This section writes the contracts that traffic flows through: a control plane for topics and subscriptions with a confirmation handshake, a publish call that returns 202 the moment the Message Log holds the message, and a delivery envelope every HTTP subscriber must answer with a 2xx within 5 seconds. We walk order #84721 across the wire, then defend four shapes: 202 instead of "delivered", no idempotency key on standard publish, the 5 s timeout, and the refusal to send to an unconfirmed URL.
The interviewer slides the marker over: "Show me the API." Before you write a path, say the thing that decides the shape: this service has two customers on two clocks (Section 2's Requirements). The publisher wants a fast, durable ack. The subscriber wants every message, at its own pace. So there are three contracts, not one: the control plane, the publish call, and the one people forget, the API we call on them.
The Whole Surface
| Purpose | Endpoint | Returns |
|---|---|---|
| Create topic | POST /v1/topics {name, type: "standard"} |
201 {topicId}, idempotent on (account, name) |
| Subscribe | POST /v1/topics/{topicId}/subscriptions |
201 {subscriptionId, status: "PendingConfirmation"} |
| Confirm | GET /v1/subscriptions/confirm?token= (the one-time confirmUrl) |
200 {status: "Confirmed"} |
| Manage | PATCH / DELETE /v1/subscriptions/{subscriptionId} |
Change filter or policies, unsubscribe |
| List | GET /v1/topics/{topicId}/subscriptions?pageToken= |
One page plus the next token |
| Publish | POST /v1/topics/{topicId}/messages {body, subject?, attributes?} |
202 {messageId} after the durable write |
| Publish batch | POST /v1/topics/{topicId}/messages:batch |
Up to 10 messages, 256 KB total |
The subscribe body is {protocol, endpoint, filterPolicy?, deliveryPolicy?, redrivePolicy?: {dlq}}. No path carries an account ID. Every request except confirm is signed with HMAC over the canonical request (SigV4-style) using the account's access keys, so the caller's identity comes from the signature. The topic's access policy then decides who may publish or subscribe.
The first four rows go to the Control Plane API; publish goes to the Publish API. They're separate services because a control-plane outage must never stop publishing.
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