API Versioning skill for Codex

Versioning is done well when most changes need no new version at all, the rare breaking change ships behind an explicit version clients opt into, and old versions are retired on a published date with evidence that remaining traffic has been contacted, not guessed.

First question: is this change breaking?

Change	Breaking?
Add an endpoint, optional request field, response field, optional query param	No
Add an enum value to a response	Usually no, if docs say enums are open; yes for strict clients
Remove or rename a field, endpoint or enum value	Yes
Make an optional request field required, or add a required param	Yes
Change a type, format, unit or default value	Yes
Change status codes, error codes or pagination semantics	Yes
Tighten validation (shorter max length, new format rule)	Yes
Change ordering of a list that clients may rely on	Treat as yes

If the change is not breaking, ship it without a version bump. If it is, first look for an additive alternative: a new field next to the old one, a new endpoint, a new optional parameter that opts into new behavior. Version only when the additive route would leave the API permanently confusing.

Choose a strategy

Strategy	How clients select	Best for	Cost
URL major version (/v1/orders)	Path	Most public and internal REST APIs	Coarse; v2 tends to be a big-bang
Media type (Accept: application/vnd.acme.v2+json)	Header	Per-resource evolution, hypermedia APIs	Harder to test in a browser, easy to forget in clients
Dated version header (Api-Version: 2026-03-01) pinned per account	Header, default from account	High-churn public APIs with many small breaks	Needs a version-transform layer and strict tests
Query param (?version=2)	Query	Rarely; caches and logs handle it poorly	Avoid for new APIs

Default recommendation: URL major version for the big structural breaks, additive evolution inside a major, and dated versions only if the team will build and maintain a transform layer. GraphQL APIs do not version; they deprecate fields (see graphql-schema-design). gRPC versions live in the proto package (acme.orders.v2).

Workflow

- [ ] 1. Confirm the change is breaking and no additive path works
- [ ] 2. Implement the new version beside the old one
- [ ] 3. Announce deprecation with headers, docs and changelog
- [ ] 4. Measure remaining usage per client
- [ ] 5. Contact, brown out, then sunset
- [ ] 6. Remove code and spec after sunset

1. Inspect

Read AGENTS.md, the OpenAPI spec and router setup. Identify how versions are routed today, where the version is logged, and which clients (API keys, apps, partners) exist.

2. Implement side by side

• Share the domain layer; version only the HTTP adapter (request parsing, response shaping). Two copies of business logic will diverge.
• For dated versions, keep the newest representation as the internal model and write one small transform per version change that downgrades responses and upgrades requests. Apply transforms in order from the client’s pinned version.

// one entry per breaking change, newest first
const changes: VersionChange[] = [
  {
    version: '2026-03-01',
    description: 'Order.total split into total_amount + currency',
    downgradeResponse: (o) => ({ ...o, total: `${o.total_amount / 100} ${o.currency}` }),
  },
];

export function renderForVersion(body: unknown, clientVersion: string) {
  return changes
    .filter((c) => c.version > clientVersion)
    .reduce((acc, c) => c.downgradeResponse(acc), body);
}

• Unknown or missing version: for URL versions that is a 404; for header versions use the client’s pinned default or the oldest supported version, never “latest” (latest as default breaks every client on each release).

3. Announce deprecation

Send standard headers on every response from the deprecated surface:

Deprecation: @1767225600
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Link: <https://developer.example.com/migrations/v1-to-v2>; rel="deprecation"; type="text/html"

• Deprecation (RFC 9745) is a structured-field date: @ plus a Unix timestamp of when the resource is or was deprecated.
• Sunset (RFC 8594) is an HTTP-date after which the resource may stop responding.
• Sunset no earlier than the deprecation date; give at least 6 months for public APIs, 12 for paid partner integrations, unless contracts say otherwise.
• Publish the migration guide, changelog entry and the date in the same release.

export function deprecated(opts: { since: Date; sunset: Date; link: string }) {
  return (req, res, next) => {
    res.set('Deprecation', `@${Math.floor(opts.since.getTime() / 1000)}`);
    res.set('Sunset', opts.sunset.toUTCString());
    res.append('Link', `<${opts.link}>; rel="deprecation"; type="text/html"`);
    req.log?.info({ deprecated: true, route: req.route?.path, client: req.clientId });
    next();
  };
}

4. Measure usage

• Log API version, route, and client identity on every request; build a query or dashboard of “requests to deprecated surface by client, last 30 days”.
• Usage counts must come from production logs or metrics, never from assumptions about who “should” have migrated.

5. Contact, brown out, sunset

• Notify remaining clients directly (email, dashboard banner) with their own usage numbers. Sending messages to customers needs the user’s explicit go-ahead.
• Brownouts: one to four weeks before sunset, return the post-sunset error for short, announced windows (for example 10 minutes, then 1 hour) so unmonitored integrations surface. Schedule them with the user; they are deliberate production failures.
• At sunset, respond 410 Gone with a problem body linking the migration guide. Keep that stub for a few months before deleting the route.

6. Remove

Delete the old adapter code, transforms, spec paths and tests in one change. Confirm the OpenAPI diff shows only the intended removals.

Gotchas

• Bumping the major version for every small break trains clients to ignore upgrades and multiplies the versions you must run.
• Versioning the whole database or service instead of the adapter doubles every bug fix.
• SDKs that default to “latest” version on upgrade make a library bump a production break for your customers; pin the version in SDK releases.
• CDN and proxy caches must vary on any version header (Vary: Api-Version) or clients receive another version’s response.
• Webhook payloads need versioning too, usually pinned to the account’s API version.

Verification

• Contract tests run against every supported version, including the transform chain.
• curl -i on a deprecated route shows Deprecation, Sunset and Link headers with correct values.
• Usage dashboard shows the deprecated surface and identifies each remaining client.
• After sunset, the route returns 410 with the migration link.

Output template

## Versioning plan: <change>
- Breaking because: <rule from table>
- Additive alternative considered: <why rejected>
- Strategy: <URL v2 | dated version 2026-03-01 | ...>
- Deprecation date / sunset date: <dates>
- Remaining clients (last 30 days): <count, top clients>
- Communication and brownout schedule: <dates, owner>
- Removal PR: <after sunset + N weeks>