1.2 KiB
ADR-0005: URI-based API versioning
- Status: Accepted
- Date: 2026-08-11
Context
The API will outlive its first client. A mobile app, marketplace connectors and partner integrations will pin to whatever exists when they are written, and some of them will never be updated.
Decision
/api/v1/..., via NestJS VersioningType.URI with defaultVersion: '1'. A version
is introduced only for a genuinely breaking change; additive fields ship inside the current
version. Old versions get a documented sunset date, not silent removal.
Consequences
The version is visible in logs, in Nginx access logs, in CDN cache keys and in a curl command. Two versions can run side by side in one process, sharing services and differing only in controllers and mappers.
URLs are slightly longer, and the version is technically part of the resource identity, which purists dislike. In exchange, nobody ever debugs a version mismatch caused by a missing header.
Alternatives considered
Header-based (Accept-Version) — rejected: invisible in logs, easy to omit, and
awkward for CDN caching. No versioning — rejected: it works right up until the first
integration nobody can update.