Section 4: Two Directions, Two Contracts - API Design (with pushback)
Executive Summary: Section 3 showed 50K comments/s in and 150M deliveries/s out. This section turns that imbalance into an API: an idempotent HTTPS POST for writes, a Server-Sent Events stream resumable by an opaque <epoch>.<offset> cursor for reads, plus scroll-back, replay and moderation endpoints. We walk Maya's comment across the wire, then defend four shapes under attack: one WebSocket for everything, 201 versus 202, a lying videoOffsetMs, and a stream keyed by video instead of user.
The interviewer uncaps the marker: "Show me the API." Before writing a path, say the fact that decides the shape: a viewer posts about once every 1,000 seconds (~17 minutes) but reads up to 10 comments a second. Two traffic patterns, thousands of times apart, get two contracts.
The Whole Surface
| Purpose | Endpoint | Who may call |
|---|---|---|
| Post a comment | POST /v1/videos/{videoId}/comments |
Any signed-in viewer |
| Live stream (SSE) | GET /v1/videos/{videoId}/comments/stream |
Any viewer |
| Scroll-back | GET /v1/videos/{videoId}/comments?before=<cursor>&limit=50 |
Any viewer |
| Replay | GET /v1/videos/{videoId}/comments?fromOffsetMs=&toOffsetMs= |
Any viewer |
| Remove | DELETE /v1/videos/{videoId}/comments/{commentId} |
Author, broadcaster, moderator |
| Settings | PUT /v1/videos/{videoId}/comment-settings |
Broadcaster, moderators |
| Pin | PUT /v1/videos/{videoId}/pinned-comment |
Broadcaster, moderators |
No path contains a user ID. The author comes only from the verified token, so no request can post as someone else.
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