APIs
OpenAPI: multiple-choice review
Crux Multiple-choice synthesis across the OpenAPI unit — spec-first vs code-first, contract drift, breaking-change gates, codegen, validation, and the 3.1 schema shift.
Your altitude — climbing toward senior
ZeroJuniorMiddleSenior
You are at senior altitude — in orbitSix questions across the whole unit. Each one is a call you make on a real API — not a definition to recite, but a decision about where the truth lives and how the pipeline keeps it honest.
Goal
Confirm you can connect spec-first vs code-first, contract drift, breaking-change gates, codegen, and edge validation into one enforcement story — the synthesis the lesson built toward.
Quiz
Completed
A team has a hand-written OpenAPI spec rendered to a nice docs portal. A teammate says 'we are covered against breaking changes.' What is actually missing?
Heads-up Clients integrate over weeks, not on your deploy day. A published spec describes the change but does not stop an engineer adding a required field and breaking every existing client in production.
Heads-up $ref reduces duplication inside a spec; it does nothing about detecting incompatible changes between spec versions. That is what a breaking-change diff is for.
Heads-up How the spec is born does not gate anything. Spec-first still needs the same oasdiff gate; otherwise a reviewed-but-incompatible change merges just as easily.
Quiz
Completed
Your hand-written docs mark a field optional, but the running server now rejects requests that omit it. What is this, and what prevents it?
Heads-up The server may be correct; the defect is that the contract and the code disagree. Bending the server to match stale docs hides the real failure — nothing keeps spec and code in sync.
Heads-up A request missing a now-required field fails identically on every retry. Drift is a process failure, not a transient one.
Heads-up A new version does not reconcile a spec that already lies about the current version. You first need the spec to track the server; versioning manages intended changes, not accidental drift.
Quiz
Completed
A public API is consumed by mobile apps you cannot force-update and three external partners. Which enforcement strategy fits?
Heads-up Code-first docs describe the current code but never compare today's contract to yesterday's. A newly-required field is faithfully documented and still breaks every old client. Code-first is fine, but it needs the same diff gate on top.
Heads-up Human review routinely misses breaking changes — narrowing a type or adding a required field looks innocuous in a 400-line diff. The reason oasdiff exists is that 'someone will catch it' does not survive a Friday deploy.
Heads-up A changelog is a wiki page by another name: it drifts, it is written after the fact, and it enforces nothing. The clients that broke would break identically with a changelog nobody re-read.
Quiz
Completed
You generate a TypeScript client from the spec and the result is full of any and loose untyped objects. What is the root cause?
Heads-up Every conforming generator produces loose output from a loose schema; that is faithful, not buggy. The fix is upstream in the contract, not the tool.
Heads-up TypeScript expresses these shapes fine when the schema is tight. The any-ridden output reflects an under-specified contract, not a language limit.
Heads-up Type quality tracks schema tightness, not which direction the spec was generated. A sloppy code-first spec generates an equally sloppy client.
Quiz
Completed
You upgrade the spec from OpenAPI 3.0 to 3.1. Which change is real and why does it matter?
Heads-up $ref is unchanged and still the way you reuse components. 3.1's schema changes are about nullability and JSON Schema alignment, not references.
Heads-up 3.1 changes the schema language, not the runtime. You still need a validator middleware at the edge to enforce requests against the spec.
Heads-up The nullability rewrite is a concrete syntactic change — a removed 'null' from a type array even registers in a diff as a type change rather than a nullable change.
Quiz
Completed
Which change to a request/response contract is backward compatible and safe to ship without a major version bump?
Heads-up Every existing client that does not send it is now rejected. Adding a required field is a classic breaking change — the exact case a diff gate must catch.
Heads-up A client may read that field; removing it breaks consumers silently. Removing response fields is breaking.
Heads-up Narrowing a type rejects previously-valid values. Tightening an existing field is breaking even though it looks like a harmless clarification.
Recap
The unit’s through-line is one enforcement story: a spec is a contract only when CI makes it load-bearing. Spec-first vs code-first decides where the truth lives and whether the contract is reviewed before code, but neither escapes the gate — validate requests at the edge, diff every PR with oasdiff so breaking changes (new required field, removed response field, narrowed type) fail the build, and feed tight schemas to the generator so codegen yields strong types. OpenAPI 3.1 moves schemas to JSON Schema 2020-12, replacing nullable with type arrays. Unenforced, the spec drifts into fiction and breaks clients.