32 lines
1.2 KiB
Markdown
32 lines
1.2 KiB
Markdown
# 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.
|