Überblick
Das API-Changelog* dokumentiert, wie sich die öffentliche Ottili ONE Unified API* (https://api.ottili.one/api/v1) im Laufe der Zeit verändert — neue Endpunkte, geänderte Felder, Deprecations und Sunset-Termine. Es ergänzt die Entwickler-Artikel zur Authentifizierung, zu OpenAPI-Downloads und zum Produktlebenszyklus.
Die öffentliche API ist der einzige dokumentierte, externe Einstiegspunkt für Ottili ONE. Sie läuft unter der Basis-URL https://api.ottili.one und ist als deny-by-default-Grenze* aufgebaut: nur die Pfade aus der öffentlichen Allowlist sind erreichbar, alles andere beantwortet die Edge (Caddy) mit 403 Forbidden.
Da die API unter einer Hauptversion (v1) betrieben wird, gibt es kein punktuelles „Changelog-Datum" für Breaking Changes. Stattdessen werden Änderungen über ein Deprecation-Register, OpenAPI-Erweiterungen und eine öffentliche Deprecation-Schnittstelle kommuniziert. Dieser Artikel erklärt, welche API-Fähigkeiten es gibt, in welchem Status sie sich befinden, und wie du Änderungen frühzeitig erkennst.
Status:* Die öffentliche API v1, das Deprecation-Register und die Deprecation-Schnittstelle sind Live*.
Wie API-Änderungen kommuniziert werden
Die Unified API verwendet URI-Pfad-Versionierung*. Die aktuelle Hauptversion ist im Pfad als /api/v1 codiert. Es existiert derzeit keine zweite öffentliche Hauptversion (/api/v2 ist nicht Teil des öffentlichen Vertrags). Innerhalb von v1 sind Änderungen rückwärtskompatibel; ein Breaking Change erhält einen neuen Pfad oder eine neue Hauptversion.
Veraltete Endpunkte werden über ein zentrales Routen-Inventar* (config/public_api/routes_inventory.yaml) verwaltet. Jede Route kann die Felder deprecated, deprecated_at, sunset_at, replacement und deprecation_notes tragen. Die generierte öffentliche OpenAPI-Dokumentation markiert veraltete Operationen standardkonform (deprecated: true) plus Ottili-spezifische Erweiterungen (x-ottili-deprecated, x-ottili-replacement, x-ottili-deprecated-at, x-ottili-sunset-at).
Status-Labels
Jede API-Fähigkeit trägt ein Lifecycle-Label. Die öffentlich sichtbaren Labels:
| Label | Bedeutung |
|---|---|
Live | Allgemein verfügbar und voll unterstützt |
Beta | Öffentlich im Vorab-Stadium verfügbar; kann sich ändern |
Private Beta | Für eine eingeladene Gruppe verfügbar |
In Development | Wird aktiv gebaut; noch nicht verfügbar |
Planned | Angenommen und eingeplant, noch nicht begonnen |
Concept | Frühe Idee in Prüfung; nicht terminiert |
(Deprecated und Disabled kennzeichnen den Ruhestand einer Route bzw. Funktion.) Hintergrund und die exakte Reihenfolge findest du unter [Funktionsstatus-Labels verstehen](/docs/understand-feature-status-labels).
Aktuelle API-Fähigkeiten und ihr Status
Die folgende Übersicht listet die öffentlich erreichbaren API-Fähigkeiten und ihren aktuellen Status. Alle Einträge sind gegen das bereitgestellte Routen-Inventar und den Public-API-Service verifiziert.
| Fähigkeit | Route / Ort | Status |
|---|---|---|
| Öffentliche API v1 (Basis) | https://api.ottili.one/api/v1 | Live |
| Deny-by-default Public Boundary (Caddy) | Edge-Regel, nur Allowlist erreichbar | Live |
| Öffentlicher Status-Endpunkt | GET /api/v1/status | Live |
| Öffentlicher Kontakt-Endpunkt | POST /api/v1/platform/public/contact | Live |
| OpenAPI-Downloads (aggregiert + pro Service) | GET /api/v1/docs/openapi/specs, /specs/{service_name}, /services, /validation, /openapi.json, /portal | Live |
| Deprecation-Register (Routen-Inventar + OpenAPI-Erweiterungen) | config/public_api/routes_inventory.yaml | Live |
| Öffentliche Deprecation-Schnittstelle | GET /api/v1/public-api/deprecations | Live |
Transparenz:* Zum jetzigen Zeitpunkt istv1die einzige öffentliche Hauptversion und hat keine aktiven Deprecation-Pläne* (der interne Versions-Middleware vermerktv1_deprecation_date: Noneund „v1 remains stable"). Keine öffentliche API-Fähigkeit befindet sich derzeit inBeta,Private Beta,In Development,PlannedoderConcept. Diese Labels sind reserviert und werden hier geführt, sobald entsprechende Fähigkeiten veröffentlicht werden.
Wie du Änderungen verfolgst
1. Deprecations abfragen:* Pollen Sie GET /api/v1/public-api/deprecations. Die Schnittstelle liefert alle im Inventar markierten Routen mit deprecated_at, sunset_at und replacement. Ist keine Route markiert, lautet der Status empty.
2. OpenAPI beobachten:* Laden Sie die Specs unter /api/v1/docs/openapi und prüfen Sie die deprecated- und x-ottili-*-Felder in Ihrer CI.
3. An v1 pinnen:* Rufen Sie immer den /api/v1-Pfad auf; wechseln Sie nicht eigenmächtig Versionen.
4. Status-Labels beachten:* Nutzen Sie die Labels, um abzuschätzen, wie stabil eine Fähigkeit ist.
Details zu Endpunkten, Authentifizierung und Rate Limits finden Sie in den verwandten Artikeln.
Bekannte Einschränkungen
- Nur v1 öffentlich:*
v2ist Teil des internen Unified-API-Vertrags, aber nicht über die öffentliche Grenze erreichbar. - Deprecation-Metadaten aus dem Inventar:* Die öffentliche Sichtbarkeit spiegelt ausschließlich
config/public_api/routes_inventory.yamlwider. - Kein festes Mindest-Ankündigungsfenster im Vertrag:* Der Vertrag erzwingt nur
sunset_at >= deprecated_at.
Verwandte Artikel
- [TypeScript SDK](/docs/typescript-sdk)
- [Funktionsstatus-Labels verstehen](/docs/understand-feature-status-labels)
- [Produktlebenszyklus und Funktionsstatus](/docs/product-lifecycle-and-feature-status)
- [Plattform- und Produkt-Schicht](/docs/platform-layer-and-product-layer)
- [Was ist Ottili ONE?](/docs/what-is-ottili-one)
- [Erste Schritte mit Ottili ONE](/docs/getting-started-with-ottili-one)
War dieser Artikel hilfreich?