Der öffentliche API-Vertrag* ist der einzige dokumentierte externe Einstiegspunkt und AI-Agent-Einstiegspunkt für Ottili ONE. Er ist eine bereinigte Teilmenge der internen Unified API: Jeder enthaltene Endpunkt ist für die öffentliche Nutzung freigegeben, interne, nur-admin, Debug-, Rohdatenbank-, lokale und private Service-Routen sind entfernt.
Das kanonische, versionierte Artefakt wird im Repository unter docs/api/openapi.public.json (sowie als YAML-Pendant docs/api/openapi.public.yaml) veröffentlicht. Die öffentliche Produktions-Basis-URL lautet https://api.ottili.one.
Was der Vertrag enthält
- Nur freigegebene öffentliche Routen* — Developer-API, öffentliche Inhalte, Plattform-, Business-, Modul- und Integrationsflächen, die für externe Entwickler gedacht sind.
- Schemas und Beispiele*, die von diesen Routen referenziert werden. Interne Schema-Definitionen, die von keiner öffentlichen Route referenziert werden, werden entfernt, damit sie nicht nach außen gelangen.
- Authentifizierung* über den
securitySchemes-Block (BearerAuthfür JWT/OAuth2,ApiKeyAuthfür Developer-API-Schlüssel). Den vollständigen Ablauf findest du unter [Öffentliche API-Authentifizierung](/docs/public-api-authentication). - Fehler* mit einem strukturierten Envelope (
ok,error,code,request_id) und Standard-HTTP-Statuscodes (4xx Client-Fehler, 5xx Server-Fehler). - Ratelimits*, dokumentiert in der Vertragsbeschreibung, über adaptive Limits erzwungen und über die Header
X-RateLimit-Limit,X-RateLimit-RemainingundRetry-Afterkommuniziert.
Was der Vertrag entfernt
Der Vertrag wird erzeugt, indem die folgenden Kategorien aus der vollständigen Unified-API-Spezifikation entfernt werden. Damit wird das Audit-Finding P0.2* der öffentlichen Website direkt adressiert (die öffentliche API-Referenz stellte zuvor interne Unified-API-Strukturen bloß).
| Entfernte Kategorie | Beispiele |
|---|---|
| Interne Admin-Routen | /api/v1/admin/*, /api/v1/platform/admin/* |
| Rohdatenbank-Routen | /api/v1/database/*, Datenbank-Pool-Endpunkte |
| Duplikat-Präfix-Routen (fehlerhaft) | /api/v1/api/v1/... |
| Debug- / Developer-Debug-Routen | /api/v1/developer/debug/*, /debugging/* |
| Lokale Dateisystem- / Dev-Artefakte | /playwright, /fsevents, /sales_manager, /Ottili_ONE/... |
| Interne Service-Flächen | internal, ssh-surface, micro-evolution, stack-manager, simulation, wall-mode, dev-orchestrator, codehelm |
| Veraltete unversionierte Routen | /api/company/*, /api/dashboard/*, /api/apps/*, /api/analytics/* |
| Migration- / Backfill-Routen | backfill, migration, /migrate, rollback |
| Spezifikations-Freigabe / Index-Verwaltung | /api/v1/docs/openapi/*, /docs/index/rebuild, /docs/index/stats |
Vertrag neu erzeugen
Der veröffentlichte Vertrag wird erzeugt, nicht von Hand bearbeitet. Nach jeder Änderung an den Unified-API-Routen wird er aus der vollständigen Spezifikation neu erzeugt:
python3 scripts/build_public_openapi.pyEin Contract-Test (tests/unit/test_public_openapi_contract.py) bereinigt die vollständige Spezifikation erneut und prüft, dass das veröffentlichte Artefakt bytegenau reproduzierbar ist, keine ausgeschlossenen Routen enthält, einen Produktions-Server (ohne localhost) deklariert und Authentifizierung, Fehler und Ratelimits dokumentiert. Wenn sich die Quelle ändert und der Vertrag nicht neu erzeugt wird, schlägt dieser Test fehl.
Status und Folgeschritte
Das bereinigte, validierte Vertrags-Artefakt ist vollständig und eingecheckt. Dass das öffentliche API-Gateway (api.ottili.one) nur* diesen Vertrag ausliefert — statt der vollständigen internen Unified API — ist eine separate Deployment-Aufgabe, damit sich externe Entwickler und Agenten auf die veröffentlichte Fläche verlassen können.
War dieser Artikel hilfreich?