Section 4: Seven Endpoints and a Doorbell - API Design (with Pushback)
Executive Summary: This section writes the full contract between the browser extension and the backend: seven endpoints covering watches, product lookups, push subscriptions, price observations and delivery acks. We settle how identity reaches the server (only inside a verified token), how money is represented (integer minor units plus an ISO currency, never floats), and why a watch is created with an idempotent PUT keyed by marketplace and ASIN. Then we hold the line through four rounds of pushback: polling versus push, PUT versus POST, trusting the extension's price, and why the path carries an ASIN instead of a URL.
The interviewer hands over the marker: "Section 3 says inbound traffic is small. Show me what the extension actually calls." It is small, about 3,500 lookups per second at the Prime Day peak. But every promise Section 2 made shows up here as a field, a status code, or a deliberate absence.
The Contract at a Glance
| Endpoint | Purpose | Success | Notes |
|---|---|---|---|
PUT /v1/watches/{marketplace}/{asin} |
Create or update my watch | 201 created / 200 updated |
Returns state, currentPrice, ETag; optional If-Match |
GET /v1/watches?cursor=&limit=50 |
List my watches | 200 |
Cursor-paginated |
DELETE /v1/watches/{marketplace}/{asin} |
Remove my watch | 204 |
Idempotent: deleting twice is still 204 |
GET /v1/products/{marketplace}/{asin} |
Product-page panel | 200 |
Current price, lastCheckedAt, low90d, myWatch |
PUT /v1/installs/{installId}/push-subscription |
Register this browser | 200 |
Body {endpoint, keys:{p256dh, auth}}; a resubscribe replaces the old one |
POST /v1/observations |
Report prices the extension saw | 202 |
Batch of at most 20, rate-limited per install |
POST /v1/notifications/{notificationId}/ack |
"I displayed it" | 204 |
Idempotent; feeds a metric only |
Study what is missing from every path: a user id. The extension signs in through OIDC, holds a 15-minute access token plus a refresh token, and the gateway derives the user from the verified token's subject and from nothing else. There is no request a client can build that names someone else's watches.
installId is the one client-chosen identifier, and it is safe because it names a browser, not a person: a UUID generated at install time, always stored under the user from the token. Maya's Chrome and Firefox are two installs and two subscriptions under one user. When a browser rotates its subscription, the extension PUTs the new one to the same installId, so endpoints are replaced, never accumulated.
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