Section 4: A Receipt That Proves Nothing - API Design (with Pushback)

Executive Summary: This section writes the contract for Northfield College's election: one read Alex makes before voting, one write that casts the ballot, two public reads after close, and a small admin surface. The cast endpoint takes identity only from the SSO token, returns a tracking code that never echoes the selections, and accepts an Idempotency-Key, so a retry after a timeout gets the same code instead of an alarming 409. The admin API has no endpoint that reads a ballot by voter, because the data to answer it doesn't exist.

Section 3 left us with 1 vote/s at peak and 400 requests/s on results. The interviewer says: "Okay. Show me the API."

Public
GET  /v1/elections/{id}                        metadata: races, window, status
GET  /v1/elections/{id}/bulletin-board?code=   is this tracking code on the board?
GET  /v1/elections/{id}/results                static results file, after close

Voter (college SSO token required)
GET  /v1/elections/{id}/ballot                 my ballot style, or why I can't vote
POST /v1/elections/{id}/ballots                cast once, get a tracking code

Admin (scoped roles; schedule changes need a second approver)
POST /v1/elections                             create a draft election
PUT  /v1/elections/{id}/races                  define races and candidates
POST /v1/elections/{id}/roll:import            load the registrar's roll
POST /v1/elections/{id}:open                   scheduled, dual control
POST /v1/elections/{id}:close                  scheduled, dual control

Notice what is missing: no GET /ballots/{id}, no endpoint that accepts a voter id, and no running tally.

Before Voting: The Ballot Read

Alex signs in with college SSO at 09:04 on day one, four minutes after the opening email. The client asks one question:

GET /v1/elections/nc-2026-spring/ballot
Authorization: Bearer <college SSO token>

200 OK
{
  "election_id": "nc-2026-spring",
  "ballot_style": "nc-standard",
  "closes_at": "2026-03-12T09:00:00-05:00",
  "races": [
    {"race_id": "president", "method": "plurality", "choose": 1,
     "candidates": ["c-11", "c-12", "c-13"]},
    {"race_id": "ref-1", "method": "yes_no"}
  ]
}

(The other three races are trimmed here, and times are college local time.) This read does three jobs. It checks the roll and returns 403 not_eligible if Alex isn't on it. It returns 409 already_voted if Alex has voted, so the client shows "you've voted" instead of an empty ballot. Otherwise it names Alex's ballot style. Candidate statements are identical for everyone with that style, so they come from the CDN.