web_sport/docs/adr/0005-uri-based-api-versioning.md

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.