Section 4: Two Timestamps and a Promise - API Design (with pushback)

Executive Summary: This section writes the contract before the machinery. We pin the interval semantics in one line of logic, design one paginated read endpoint plus a count and an async export, and define ingest as a Kafka event schema instead of an RPC. Then we defend it through seven rounds of pushback, each answered with a number from Section 3.

The interviewer caps the marker: "Walk me through your API." The tempting move is to write a URL. The candidate writes a sentence first.

"Before any endpoint, let me write down what 'active' means, because every bug in this system will be a disagreement about that sentence."

The Semantics, Written Before the Endpoint

• An event is half-open: [start_ts, end_ts). A ride that ends at 17:10:00 is not active at 17:10:00.
• The query window is closed: [qs, qe].
• An event is active in the window iff start_ts <= qe AND (end_ts IS NULL OR end_ts > qs).
• qs = qe is a legal point query: "what was in progress at exactly 17:31?"
• qe is clamped to now. Nobody gets a promise about the future.

Run the three rides through it. Maya's ride trip_8f3a (16:52:10 → 17:31:45) passes both predicates, even though it started before the window. trip_c41e (started 17:38:20, still going) passes because its end is null. trip_77d0 ended at 17:09:59, which is not after 17:10:00, so it is out.

Key Insight: Half-open events plus a closed window is deliberate: a point query at 17:10:00 returns the ride starting then, not the one ending then.