Versioning
The /v1 rule
Section titled “The /v1 rule”The version lives in the URL path: https://api.doesitarm.com/v1/…. Within a version we
make additive changes only — new endpoints, new optional fields, new enum values you can
safely ignore. We never rename or remove a field, change a type, or change the meaning of an
existing value inside v1.
A change that would break a careful client — removing a field, narrowing a type, changing
semantics — only ships under a new path version (/v2), and /v1 keeps working during a
published deprecation window.
Write forward-compatible clients: ignore fields you don’t recognize, and don’t treat the
status, basis, confidence, or field enums as exhaustively closed forever — a future
additive value should degrade gracefully, not crash your parser.
Two version numbers, on purpose
Section titled “Two version numbers, on purpose”You’ll see two numbers and they mean different things:
| Number | Where | What it tracks |
|---|---|---|
/v1 | the URL | the wire contract — bumped only on a breaking change |
info.version (1.0.0) | the OpenAPI spec | the document — bumped on every additive revision too |
So you can see info.version climb to 1.4.0 while the URL stays /v1: the spec gained
optional fields and endpoints, none of them breaking. When the URL would need to become
/v2, info.version goes to 2.0.0.
Tracking changes
Section titled “Tracking changes”- Human-readable: the API changelog.
- Machine-readable: the change feed tracks
data changes (verdicts moving); the OpenAPI spec and its
info.versiontrack contract changes. They’re different feeds for different jobs.