Section 4: Declare It, Don't Command It - API Design (with Pushback)

Executive Summary: The deploy system has four contracts. CI registers an immutable release by digest and, on merge, starts a rollout that runs for hours. Humans steer it with pause, resume, rollback and freeze. And 100,000 host agents watch for their desired state and report what they actually run. Every contract is declarative and idempotent, because callers retry, operations outlive any HTTP request, and two people can act on the same rollout within seconds. The interviewer pushes on five shapes: who registers the release, mutable tags, the 202, If-Match on resume, and pull versus push.

The interviewer nods at the Section 3 numbers. "Small control plane, fine. Show me the interfaces."

You: "Four callers with very different needs: CI, engineers, on-call humans, and an agent on every host. I'll take them in the order Sam's release r-1432 meets them."

Releases: Registered Once, by Digest

When CI finishes building commit a1b2c3d, it registers the result:

POST /v1/services/checkout-api/releases
{
  "digest": "sha256:9f4e…",
  "commit": "a1b2c3d",
  "provenance": { "builder": "ci", "source": "checkout-api@a1b2c3d" },
  "signature": "<CI signature over digest and provenance>"
}
→ 201 Created
{ "release_id": "r-1432", "status": "candidate" }

There is no PUT or PATCH. The digest, commit and provenance never change; only the system moves the status (candidate, deployed, bad). A retried POST with the same digest returns the existing release, so CI can retry freely.

Interviewer: "Why does CI register it? The deploy system could build from the commit itself."

You: "Then the bytes we canary aren't provably the bytes we ship. We build once and promote that same digest through every stage. A rebuild per environment can pick up a different base image or dependency, and then the canary tested something else. It also keeps the signature meaningful: CI signs what it built and tested, and agents refuse anything unsigned (Section 10 covers that chain)."

Interviewer: "Can I deploy checkout-api:latest?"

You: "No. The API takes release IDs, and each maps to one digest. The CLI may resolve a tag for convenience, but it sends the digest it resolved, and the digest is what gets audited. A tag that moves between the canary and region C means different hosts ran different code under one name." This choice never flips.

Quick check before moving on: