Section 4: Two Doors, One Promise - API Design (with Pushback)
Executive Summary: A job scheduler has two very different callers: tenants who define work and tenant workers who do it. We give each its own contract, write the running example's create request in full, then take four rounds of pushback on the choices that matter most: server-side cron evaluation, pull-based workers, the refusal to promise exactly-once, and deterministic run ids. Every answer traces back to Section 2's "late, never lost" promise.
The interviewer taps the whiteboard: "Show me how a team actually uses this." The weak move is to list CRUD endpoints. The strong move is to notice that two different callers are knocking on two different doors, and to design each door for the caller behind it.
Two Audiences, Two Surfaces
Section 3's numbers already split the traffic. Different callers, rates and failure modes mean two contracts:
| Tenant API | Worker API | |
|---|---|---|
| Caller | Services, pipelines, humans | Tenant workers, through our SDK |
| Style | REST/JSON (gRPC also offered) | gRPC, long-lived connections |
| Rate | ~700 writes/s (3,500 peak), ~2,500 reads/s (10,000 peak) | ~3,000 calls/s avg, 30,000/s peak |
| Latency promise | create/cancel p99 ≤ 200 ms, reads p99 ≤ 100 ms | Long-poll by design; the rest is cheap |
| Its job | Define what runs and when | Report what actually happened |
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