> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0118 — @stackra/versioning is built now and stays dormant: date versions pinned per API key or OAuth app

> Accepted, amended by 0136 · 2026-10-19

> [!NOTE]
>
> Amended by [0136](/adr/0136-action-runtime-contract): REST and MCP map date versions to action
> versions, with a sunset of at least 6 months for public APIs.

## Context

[0037](/adr/0037-api-versioning-by-date-header) proposed Stripe-style date versioning through a `Stackra-Version`
header and left open whether it is a package or middleware. The research found that reference implementations put it in a
response-transform chain, and that an earlier over-built version in the Figentra export (about 3,000 lines) was deleted
unused. Endpoints themselves stay immutable under the HTTP conventions rule. The owner chose to build the package now, so the
first external consumer does not force a rushed design.

## Decision

1. **V1 — `@stackra/versioning` is built now and is dormant at launch**: while only the latest version exists, it does nothing.
2. **It is a response-only transform chain.** Each breaking change adds one dated transform that turns the latest response into
   the previous shape. Requests are not transformed. Outbound webhooks pass through the same chain.
3. **V2 — A client's version is pinned per API key or OAuth app** when it is created. A `Stackra-Version` header overrides the
   pin for one request.
4. **A version is supported for 12 months** after its successor ships. Responses on an old version carry `Deprecation` and
   `Sunset` headers.
5. **OpenAPI is published for the latest version only**, with a changelog of the dated transforms.
6. **Paths stay unversioned**, and integration events keep their `.vN` names ([0078](/adr/0078-messaging-layer-eight-packages)).

## Consequences

* The first breaking change costs one transform, not a framework.
* Every dated transform is a maintenance cost until its version sunsets.
* The HTTP conventions rule's "no versions" line must point here: endpoints stay immutable, responses are versioned.

## Enforcement

Planned: a contract test per dated transform; a check that no route path matches `/v\d+/`; a test that a response on a sunset
version is refused. Nothing checks this today.

## Supersedes and sources

Supersedes: [0037](/adr/0037-api-versioning-by-date-header) (decisions 1 to 3 restated; decision 4 settled as a package). Sources: owner decisions in chat, 2026-10-19 (Round 11 V1, V2; API versioning research).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.