Referència de l'API OSL

Aquesta secció defineix els contractes públics del motor OSL. El que estableix és el que qualsevol client pot assumir, i el que qualsevol motor OSL-conforme **HA D’**implementar exactament.

Per a la semàntica completa dels objectes (quines primitives existeixen, els seus camps) vegeu l’especificació. Aquí: com es crida i què retorna.

Superfícies

OSL v1 exposa quatre superfícies separades:

Superfície	Qui la consumeix	Forma
REST	Eines de BI, apps, dashboards, scripts	HTTP/JSON · Arrow IPC opcional per al bulk de /query
Tools MCP	Agents d’IA (Claude, GPT, Copilot, custom)	definicions de tools sobre el protocol MCP
CLI	Desenvolupadors, pipelines de CI	el binari osl
Esdeveniments OpenLineage	Marquez, DataHub, observabilitat	emissor via webhook / kafka

Un sol endpoint de consum

Tot el que llegeixes passa per un únic endpoint — /osl/query. L’analítica estructurada, les mètriques, el retrieval vectorial governat, els registres d’entitat i la travessa de grafs són tots formes de la superfície OSL-SQL.

Els cinc endpoints ara són un

Els antics endpoints /osl/retrieve, /osl/joint/resolve i /osl/traverse s’han eliminat — cadascun és una forma de /osl/query (RETRIEVE(...), un select de registre Joint, TRAVERSE(...)). Això és el que fa que “OSL és l’única capa de consum” sigui literalment cert.

Endpoint	Propòsit
POST /osl/query	La superfície de consum — OSL-SQL (osql), sql cru, o MetricFlow
POST /osl/sample	Preview de contingut governat — ACL + redacció server-side (no una query d’àlgebra)
GET /osl/domain-map	El graf de domini unificat (Entities, mètriques, candidats)
GET /osl/schema	El manifest compilat (cacheable)
GET /osl/schema/resolve	Resolutor de lexicon — terme de negoci → FQN canònic
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Autoria assistida (draft → validate → publish)
GET /osl/candidates	Descobriment — entitats candidates (encara no adoptades)
GET /osl/conformance	Nivells de conformança declarats
GET /health	Health check sense autenticació

La superfície de query (OSL-SQL)L'únic endpoint i les seves cinc formes.

Retrieval (RETRIEVE)Retrieval vectorial governat com a font de relació.

AutenticacióCadenes de delegació atestades, scopes, rate limits.

Errors i codis d'estatL'envelope d'error i les bandes de codis E.

Tools MCP

OSL inclou tools MCP que qualsevol agent pot invocar: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Criden els mateixos resolutors governats que hi ha darrere de les formes OSL-SQL — doc_search embolcalla RETRIEVE, entity_get embolcalla la forma de registre Joint — així un agent obté la mateixa aplicació que qualsevol altre consumidor.

Versionat de l’API

/osl/ és l’arrel de v1. Una v2 amb canvis disruptius viuria a /osl/v2/ mentre /osl/ continua servint el contracte v1 durant almenys dues versions menors consecutives. Els endpoints PODEN afegir camps de resposta opcionals dins de v1.x; els clients **HAN D’**ignorar els camps no reconeguts.