Référence de l’API OSL

Cette section définit les contrats publics du moteur OSL. Ce qui y est affirmé est ce que tout client peut supposer, et ce que tout moteur conforme à OSL DOIT implémenter exactement.

Pour la sémantique complète des objets (quelles primitives existent, leurs champs), voir la spécification. Ici : comment on l’invoque et ce qu’il renvoie.

Surfaces

OSL v1 expose quatre surfaces distinctes :

Surface	Qui la consomme	Forme
REST	Outils de BI, apps, dashboards, scripts	HTTP/JSON · Arrow IPC optionnel pour le bulk de /query
Tools MCP	Agents d’IA (Claude, GPT, Copilot, custom)	définitions de tools sur le protocole MCP
CLI	Développeurs, pipelines de CI	le binaire osl
Événements OpenLineage	Marquez, DataHub, observabilité	émetteur webhook / kafka

Un seul endpoint de consommation

Tout ce que vous lisez passe par un seul endpoint — /osl/query. L’analytique structurée, les métriques, le retrieval vectoriel gouverné, les enregistrements d’entités et la traversée de graphe sont tous des formes de la surface OSL-SQL.

Les cinq endpoints n’en font plus qu’un

Les anciens endpoints /osl/retrieve, /osl/joint/resolve et /osl/traverse ont été supprimés — chacun est une forme de /osl/query (RETRIEVE(...), un select d’enregistrement Joint, TRAVERSE(...)). C’est ce qui rend littéralement vraie l’affirmation « OSL est l’unique couche de consommation ».

Endpoint	Objectif
POST /osl/query	La surface de consommation — OSL-SQL (osql), sql brut, ou MetricFlow
POST /osl/sample	Prévisualisation de contenu gouvernée — ACL + caviardage server-side (pas une query d’algèbre)
GET /osl/domain-map	Le graphe de domaine unifié (Entities, métriques, candidates)
GET /osl/schema	Le manifest compilé (cacheable)
GET /osl/schema/resolve	Resolver du lexicon — terme métier → FQN canonique
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Authoring assisté (draft → validate → publish)
GET /osl/candidates	Découverte — entités candidates (pas encore adoptées)
GET /osl/conformance	Niveaux de conformité déclarés
GET /health	Health check sans authentification

La surface de query (OSL-SQL)L’endpoint unique et ses cinq formes.

Retrieval (RETRIEVE)Retrieval vectoriel gouverné comme source de relation.

AuthentificationChaînes de délégation attestées, scopes, rate limits.

Erreurs et codes de statutL’envelope d’erreur et les bandes d’E-codes.

Tools MCP

OSL inclut des tools MCP que tout agent peut invoquer : metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Ils appellent les mêmes resolvers gouvernés qui sous-tendent les formes OSL-SQL — doc_search enveloppe RETRIEVE, entity_get enveloppe la forme d’enregistrement Joint — de sorte qu’un agent obtient le même enforcement que n’importe quel autre consommateur.

Versionnage de l’API

/osl/ est la racine v1. Une v2 avec des changements incompatibles vivrait dans /osl/v2/ tandis que /osl/ continue de servir le contrat v1 pendant au moins deux versions mineures consécutives. Les endpoints PEUVENT ajouter des champs de réponse optionnels au sein de v1.x ; les clients DOIVENT ignorer les champs non reconnus.