OSL-API-Referenz

Dieser Abschnitt definiert die öffentlichen Verträge der OSL-Engine. Was hier festgehalten wird, ist das, was jeder Client annehmen darf, und was jede OSL-konforme Engine MUSS exakt implementieren.

Für die vollständige Objekt-Semantik (welche Primitiven existieren, ihre Felder) siehe die Spezifikation. Hier: wie sie aufgerufen wird und was sie zurückgibt.

Oberflächen

OSL v1 stellt vier separate Oberflächen bereit:

Oberfläche	Wer sie konsumiert	Form
REST	BI-Tools, Apps, Dashboards, Skripte	HTTP/JSON · optional Arrow IPC für /query-Bulk
MCP-Tools	AI-Agenten (Claude, GPT, Copilot, custom)	Tool-Definitionen über das MCP-Protokoll
CLI	Entwickler, CI-Pipelines	das osl-Binary
OpenLineage-Events	Marquez, DataHub, Observability	Webhook-/Kafka-Emitter

Ein Konsum-Endpoint

Alles, was du liest, läuft durch einen einzigen Endpoint — /osl/query. Strukturierte Analytik, Metriken, gesteuertes Vektor-Retrieval, Entity-Datensätze und Graph-Traversierung sind alle Formen der OSL-SQL-Oberfläche.

Die fünf Endpoints sind jetzt einer

Die früheren Endpoints /osl/retrieve, /osl/joint/resolve und /osl/traverse wurden entfernt — jeder ist eine Form von /osl/query (RETRIEVE(...), ein Joint-Datensatz-Select, TRAVERSE(...)). Genau das macht „OSL ist die einzige Konsumschicht“ buchstäblich wahr.

Endpoint	Zweck
POST /osl/query	Die Konsum-Oberfläche — OSL-SQL (osql), rohes sql oder MetricFlow
POST /osl/sample	Gesteuerte Content-Vorschau — ACL + serverseitige Redaktion (keine Algebra-Query)
GET /osl/domain-map	Der vereinheitlichte Domain-Graph (Entities, Metriken, Kandidaten)
GET /osl/schema	Das kompilierte Manifest (cacheable)
GET /osl/schema/resolve	Lexicon-Resolver — Business-Begriff → kanonischer FQN
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Assistiertes Authoring (draft → validate → publish)
GET /osl/candidates	Discovery — Kandidaten-Entities (noch nicht adoptiert)
GET /osl/conformance	Deklarierte Konformitätsstufen
GET /health	Health-Check ohne Authentifizierung

Die Query-Oberfläche (OSL-SQL)Der einzige Endpoint und seine fünf Formen.

Retrieval (RETRIEVE)Gesteuertes Vektor-Retrieval als Relationsquelle.

AuthentifizierungAttestierte Delegationsketten, Scopes, Rate-Limits.

Fehler & StatuscodesDas Error-Envelope und die E-Code-Bänder.

MCP-Tools

OSL liefert MCP-Tools, die jeder Agent aufrufen kann: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Sie rufen dieselben gesteuerten Resolver auf, die die OSL-SQL-Formen unterlegen — doc_search kapselt RETRIEVE, entity_get kapselt die Joint-Datensatz-Form — sodass ein Agent dieselbe Durchsetzung erhält wie jeder andere Konsument.

API-Versionierung

/osl/ ist die v1-Wurzel. Eine v2 mit Breaking Changes würde unter /osl/v2/ leben, während /osl/ den v1-Vertrag mindestens zwei aufeinanderfolgende Minor-Versionen lang weiter bedient. Endpoints DÜRFEN innerhalb von v1.x optionale Response-Felder ergänzen; Clients MÜSSEN unbekannte Felder ignorieren.