Dokumentationsstandard

Dieser Standard gilt für jede Änderung an der öffentlichen REST-API, am Kalenderfeed und an ausgehenden Webhooks. Ziel ist ein nachvollziehbarer Vertrag für Integrationen, ohne interne Implementierungsdetails preiszugeben.

Quelle der Wahrheit

Die OpenAPI-Datei /openapi/public-v1.yaml (apps/docs/public/openapi/public-v1.yaml) ist die verbindliche Quelle für den öffentlichen REST-Vertrag. Markdown-Seiten erklären den Vertrag auf Deutsch; sie dürfen ihm nicht widersprechen.

Reihenfolge bei einer Vertragsänderung:

1. OpenAPI anpassen.
2. Referenz, Quickstart und bei Bedarf Webhooks und Kalender nachziehen.
3. Änderungen aktualisieren, bevor ein inkompatibles Verhalten ausgeliefert wird.
4. apps/e2e/tests/integrations.spec.ts an den neuen Vertrag anpassen.

Code in packages/api und apps/server/src/routes/integration.ts muss dem OpenAPI-Dokument entsprechen. Weichen Build und Spezifikation voneinander ab, ist die Änderung nicht fertig.

URI-Versionierung

Die öffentliche REST-API versioniert über den Pfad /v1/, nicht über Header:

• /api/public/v1/courses
• /api/public/v1/courses/{courseId}
• /api/public/v1/bookings
• /api/calendar/v1/{token}.ics

Kompatible Ergänzungen (optionale Felder, neue Scopes ohne Pflicht) bleiben in /v1/. Eine inkompatible Änderung, etwa entfernte Felder, eine geänderte Bedeutung, eine andere Fehlerform oder neue Pflicht-Header, braucht eine neue URI-Version (/v2/) und einen Changelog-Eintrag vor der Auslieferung. /v1/ bleibt dann so lange erreichbar, bis der Changelog ein Enddatum nennt.

Die Widget-API unter /api/widget/v1/ versioniert getrennt und gehört nicht in public-v1.yaml.

Changelog vor inkompatiblen Änderungen

Jeder sichtbare Vertragswechsel steht in Änderungen. Das gilt auch für Beta. Eine Änderung, die Verhalten bricht, ohne Changelog-Eintrag und ohne OpenAPI-Aktualisierung, erfüllt die Definition of Done nicht.

Als inkompatible Änderungen gelten insbesondere:

• entfernte oder umbenannte Felder in data
• andere HTTP-Statuscodes oder error.code-Werte
• Pflicht-Scope, der bisher nicht nötig war
• kleineres Rate-Limit oder kleineres Buchungslimit
• Einführung von Cursor-Pagination, die bestehende Clients ohne Cursor ausschließt

CI-Prüfungen

Zwei automatisierte Gates sichern den Vertrag:

Prüfung	Befehl / Artefakt	Zweck
Docs-Build	npx turbo run build --filter=docs	Starlight-Build plus scripts/check-docs.mjs
Integrations-E2E	apps/e2e/tests/integrations.spec.ts, apps/e2e/tests/integrations-webhook-catalog.spec.ts	echter Happy Path über API, Kalender und Eventkatalog

Der Docs-Build muss die OpenAPI-Datei als statische Datei nach /openapi/public-v1.yaml kopieren und redaktionelle Checks bestehen. Die E2E-Suite deckt die Widget-API nicht ab und darf keine Produktivschlüssel verwenden.

Lokal reicht zuerst der Docs-Build, danach der kleinste relevante E2E-Lauf mit integrations.spec.ts. Ohne beide Nachweise gilt die API-Änderung als unverifiziert.

Redaktionelle Pflicht

Dokumentation gehört in denselben Arbeitsumfang wie die Verhaltensänderung. Secrets, Klartext-Keys (orb_api_, orb_cal_, whsec_) und interne IDs dürfen nicht in Beispielen stehen; Platzhalter sind YOUR_API_KEY und YOUR_CALENDAR_TOKEN. Der redaktionelle Ablauf steht in Qualität und Prozess.