Section 4: The API Nobody Gets to Call - API Design (with Pushback)

Executive Summary: The API everyone expects — GET /check?ip=… — is the one this system must never expose, because any network check endpoint recreates the hot-path dependency Section 3's arithmetic killed (D1). Instead there are four surfaces, each shaped by its caller: an in-process edge SDK that answers ALLOW/DENY in microseconds and never throws or blocks; an observation intake where edges batch-report never-seen IPs to feed the crawl scheduler's priorities; a vendor adapter that is the only code in the company allowed to spend the 120 req/s SentinelDB budget (D7); and a policy and override API where country rules and manual overrides are audited, versioned and canaried (D10, D11). Three rounds of pushback test the choices — including the request you will actually get from other teams: "just give us the check endpoint."

The interviewer uncaps the marker: "Fine, the vendor is a data source. Show me the contracts." The trap is to start drawing a validation service with a REST API. Say the inversion out loud instead: the one thing every caller wants — "is this IP allowed?" — is answered by a library call against local memory, not by any endpoint. The network APIs exist only to move data around behind that call. Four surfaces, four callers.

Surface One: The Edge SDK — a Function, Not a Service

Every request router at all 30 PoPs embeds the filter and calls it before routing:

interface IpFilter {
  check(ip: string): Verdict;   // in-process, ≤ 2 µs, never throws, never blocks
}

type Verdict = {
  action: "ALLOW" | "DENY";
  ruleSource: "override" | "country" | "vendor" | "none";
  snapshotVersion: number;      // e.g. 5890 — the exact rule set that decided
  supportCode?: string;         // present on DENY
};

The contract makes two promises, and they are the whole design in miniature. check never blocks: it reads the current compiled snapshot from memory — the ≤ 10 MB artifact of ranges from Section 3 — and touches no network (D1). And it never throws: a malformed IP, a missing snapshot at boot, a corrupt delta — every failure degrades to a defined verdict under the fail posture of D4, never to an exception in 5M requests per second of hot path. A never-seen IP returns ALLOW with ruleSource: "none" — that is fail-open, counted, and it feeds Surface Two.

On DENY, the edge answers the client itself:

HTTP/1.1 403 Forbidden
{ "error": "access_denied",
  "supportCode": "IPV-FRA-5890-7C21A",
  "appeal": "https://support.twitter-scale.example/ip-appeal" }

The support code encodes PoP, snapshot version and a decision sample ID, so trust & safety can answer "why was this IP denied at 14:32?" with the exact rule source and list version (D11) — and the appeals path in Section 9 starts from it.

Quick check before moving on: