ADR-007: API-Basis-URL und Versionierungsstrategie¶

Stand: 12.08.2026 16:55 Branch: main Status: Akzeptiert

Datum, Uhrzeit	Version	Änderung	Autor
12.08.2026 16:55	1.1	Verweise auf historische UC00-OpenAPI-Blöcke an neuen Nachweisort angepasst	Codex
01.08.2026 14:55	1.0	Kopfbereich vereinheitlicht	David Mittig

Datum: 2024-01
Kontext: UC00 Schritt 4 – OpenAPI Spezifikation, Block 1 Auth & Invitation

Kontext¶

Die DiveLogix360 API benötigt eine eindeutige, stabile Basis-URL. Zwei Varianten wurden evaluiert:

Variante A: Dedizierte Subdomain https://api.divelogix360.ch/v1
Variante B: Pfad-basiert https://divelogix360.ch/api/v1

Zusätzlich wurde die Versionierungsstrategie (URL-basiert vs. Header-basiert) entschieden.

Entscheidung¶

Gewählt: Variante A — https://api.divelogix360.ch/v1

URL-basierte Versionierung (/v1/), nicht Header-basiert.

Begründung¶

Variante A (gewählt): `https://api.divelogix360.ch/v1`¶

Vorteile: - Klare Trennung zwischen Frontend (divelogix360.ch) und Backend-API (api.divelogix360.ch) - Eigene DNS-Einträge ermöglichen unabhängiges Routing, Caching (CDN) und Rate-Limiting - TLS-Zertifikat kann separat ausgestellt und erneuert werden - Unterschiedliche CORS-Policies möglich (API akzeptiert nur bekannte Origins) - API kann auf eigenem Server laufen (Hetzner Cloud), Frontend auf CDN - Professionell und industrieüblich für SaaS-Produkte

Nachteile: - Erfordert separaten DNS-Eintrag (api.divelogix360.ch) - DNS-Eintrag muss bei Go-Live auf Hetzner Cloud gesetzt werden

Variante B (abgelehnt): `https://divelogix360.ch/api/v1`¶

Vorteile: - Kein separater DNS-Eintrag nötig - Sofort nutzbar ohne DNS-Konfiguration

Nachteile: - Kein klarer Schnitt zwischen Frontend und API - CORS-Konfiguration komplexer (gleicher Origin, unterschiedliche Pfade) - Reverse-Proxy-Regeln (Nginx/Traefik) fehleranfälliger - Schwerer zu skalieren: API und Frontend teilen denselben Einstiegspunkt - Höheres Sicherheitsrisiko: Path-basiertes Routing öffnet mehr Angriffsfläche bei Fehlkonfiguration des Reverse-Proxy

URL-basierte Versionierung (gewählt)¶

Vorteile gegenüber Header-basierter Versionierung: - Einfach sichtbar und nachvollziehbar (/v1/ im Pfad) - Gut cachebar (CDN, Browser) - Keine spezielle Client-Konfiguration nötig - Einfach in Logs und Monitoring erkennbar

Sicherheitsanforderungen (beide Varianten)¶

Unabhängig von der gewählten Variante gelten folgende Sicherheitsanforderungen:

Anforderung	Details
TLS 1.3	Pflicht auf allen Endpoints — kein HTTP erlaubt
HSTS	`Strict-Transport-Security: max-age=31536000; includeSubDomains`
CORS	Nur explizit erlaubte Origins (`Access-Control-Allow-Origin`)
Tokens in URL	Verboten — API-Keys, Tokens und Credentials niemals als Query-Parameter
Rate Limiting	Auf allen Endpoints aktiv (`X-RateLimit-*`, `Retry-After` Header)

Versionierungsstrategie¶

Aspekt	Entscheidung
Schema	URL-basiert (`/v1/`, `/v2/`)
Breaking Changes	Neue Version (`/v2/`), alte Version mind. 12 Monate parallel
Non-Breaking Changes	Neue optionale Felder → keine neue Version nötig
Deprecation	Ankündigung mind. 6 Monate vor Abschaltung

Konsequenzen¶

Positiv: Klare Architektur, einfaches Scaling, professionelle URL-Struktur
Positiv: CORS und Sicherheitskonfiguration klar getrennt von Frontend
Negativ (minimal): DNS-Eintrag api.divelogix360.ch muss bei Go-Live gesetzt werden
Massnahme: DNS-Konfiguration ist Teil der Go-Live-Checkliste (Hetzner Cloud)

Entwicklungsphase¶

api.divelogix360.ch ist während der Entwicklungsphase ein Platzhalter.
Der DNS-Eintrag wird bei Go-Live auf Hetzner Cloud gesetzt.
In der lokalen Entwicklung wird localhost:3000/v1 verwendet.

Betroffene Dateien¶

Datei	Anmerkung
`docs/evidence/historical/api/uc00/openapi-block1-auth.yaml`	`servers` URL, `info.description` (Inline-Zusammenfassung)
`docs/evidence/historical/api/uc00/openapi-block2-tenants.yaml`	`servers` URL
`docs/evidence/historical/api/uc00/openapi-block3-users.yaml`	`servers` URL
`docs/evidence/historical/api/uc00/openapi-block4-onboarding.yaml`	`servers` URL
`docs/api/api-overview.md`	Abschnitt Versionierung & Sicherheitshinweise