Basic Architecture of Sport Web

2026-08-11 13:37:25 +07:00
commit 8032fff6ac
262 changed files with 20348 additions and 0 deletions
@@ -0,0 +1,31 @@
+# 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.