Riferimento API OSL

Questa sezione definisce i contratti pubblici del motore OSL. Ciò che qui si afferma è quello che qualsiasi client può assumere, e quello che qualsiasi motore conforme con OSL DEVE implementare esattamente.

Per la semantica completa degli oggetti (quali primitive esistono, i loro campi) vedi la specifica. Qui: come si invoca e cosa restituisce.

Superfici

OSL v1 espone quattro superfici separate:

Superficie	Chi la consuma	Forma
REST	Tool di BI, app, dashboard, script	HTTP/JSON · Arrow IPC opzionale per il bulk di /query
Tool MCP	Agenti di IA (Claude, GPT, Copilot, custom)	definizioni di tool sul protocollo MCP
CLI	Sviluppatori, pipeline di CI	il binario osl
Eventi OpenLineage	Marquez, DataHub, observability	emettitore webhook / kafka

Un endpoint di consumo

Tutto ciò che leggi passa per un unico endpoint — /osl/query. Analitica strutturata, metriche, retrieval vettoriale governato, record di entità e attraversamento del grafo sono tutte forme della superficie OSL-SQL.

I cinque endpoint ora sono uno

I vecchi endpoint /osl/retrieve, /osl/joint/resolve e /osl/traverse sono stati rimossi — ognuno è una forma di /osl/query (RETRIEVE(...), un select di record Joint, TRAVERSE(...)). È ciò che rende letteralmente vero “OSL è il solo strato di consumo”.

Endpoint	Scopo
POST /osl/query	La superficie di consumo — OSL-SQL (osql), sql grezzo, o MetricFlow
POST /osl/sample	Anteprima di contenuto governata — ACL + oscuramento server-side (non è una query di algebra)
GET /osl/domain-map	Il grafo di dominio unificato (Entity, metriche, candidati)
GET /osl/schema	Il manifest compilato (cacheable)
GET /osl/schema/resolve	Resolver del lexicon — termine di business → FQN canonico
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Authoring assistito (draft → validate → publish)
GET /osl/candidates	Discovery — entità candidate (non ancora adottate)
GET /osl/conformance	Livelli di conformità dichiarati
GET /health	Health check senza autenticazione

La superficie di query (OSL-SQL)L'unico endpoint e le sue cinque forme.

Retrieval (RETRIEVE)Retrieval vettoriale governato come sorgente di relazione.

AutenticazioneCatene di delega attestate, scope, rate limit.

Errori e codici di statoL'envelope di errore e le bande di E-code.

Tool MCP

OSL include tool MCP che qualsiasi agente può invocare: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Chiamano gli stessi resolver governati che stanno dietro le forme OSL-SQL — doc_search avvolge RETRIEVE, entity_get avvolge la forma di record Joint — così un agente ottiene la stessa applicazione di qualsiasi altro consumatore.

Versionamento dell’API

/osl/ è la radice v1. Una v2 con cambiamenti incompatibili vivrebbe in /osl/v2/ mentre /osl/ continua a servire il contratto v1 per almeno due versioni minori consecutive. Gli endpoint POSSONO aggiungere campi di risposta opzionali entro v1.x; i client DEVONO ignorare i campi non riconosciuti.