Referencja API OSL

Ta sekcja definiuje publiczne kontrakty silnika OSL. To, co tu napisano, jest tym, co może zakładać każdy klient, i tym, co każdy zgodny z OSL silnik MUSI zaimplementować dokładnie.

Po pełną semantykę obiektów (które prymitywy istnieją, ich pola) zajrzyj do specyfikacji. Tutaj: jak się to wywołuje i co zwraca.

Powierzchnie

OSL v1 eksponuje cztery odrębne powierzchnie:

Powierzchnia	Kto ją konsumuje	Kształt
REST	Narzędzia BI, aplikacje, dashboardy, skrypty	HTTP/JSON · opcjonalnie Arrow IPC dla /query bulk
Narzędzia MCP	Agenci AI (Claude, GPT, Copilot, custom)	definicje narzędzi nad protokołem MCP
CLI	Deweloperzy, pipeline’y CI	binarka osl
Zdarzenia OpenLineage	Marquez, DataHub, observability	emitter webhook / kafka

Jeden endpoint konsumpcji

Wszystko, co odczytujesz, przechodzi przez jeden endpoint — /osl/query. Analityka ustrukturyzowana, metryki, nadzorowany retrieval wektorowy, rekordy encji i trawersacja grafu — wszystko to formy powierzchni OSL-SQL.

Pięć endpointów to teraz jeden

Dawne endpointy /osl/retrieve, /osl/joint/resolve i /osl/traverse zostały usunięte — każdy z nich to forma /osl/query (RETRIEVE(...), select rekordu Joint, TRAVERSE(...)). To właśnie czyni zdanie „OSL to jedyna warstwa konsumpcji“ dosłownie prawdziwym.

Endpoint	Cel
POST /osl/query	Powierzchnia konsumpcji — OSL-SQL (osql), surowy sql lub MetricFlow
POST /osl/sample	Nadzorowany podgląd treści — ACL + redakcja po stronie serwera (nie jest zapytaniem algebry)
GET /osl/domain-map	Ujednolicony graf domeny (Entities, metryki, kandydaci)
GET /osl/schema	Skompilowany manifest (cacheowalny)
GET /osl/schema/resolve	Resolver leksykonu — termin biznesowy → kanoniczny FQN
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Wspomagane autorowanie (draft → validate → publish)
GET /osl/candidates	Discovery — encje kandydujące (jeszcze nie zaadoptowane)
GET /osl/conformance	Zadeklarowane poziomy conformance
GET /health	Nieuwierzytelniony health check

Powierzchnia zapytań (OSL-SQL)Jeden endpoint i jego pięć form.

Retrieval (RETRIEVE)Nadzorowany retrieval wektorowy jako źródło relacji.

UwierzytelnianiePoświadczone łańcuchy delegacji, scope'y, limity tempa.

Błędy i kody statusuEnvelope błędu i pasma E-kodów.

Narzędzia MCP

OSL dostarcza narzędzia MCP, które może wywołać dowolny agent: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. Wywołują te same nadzorowane resolvery, które stoją za formami OSL-SQL — doc_search opakowuje RETRIEVE, entity_get opakowuje formę rekordową Joint — więc agent dostaje to samo egzekwowanie co każdy inny konsument.

Wersjonowanie API

/osl/ to korzeń v1. Łamiące zgodność v2 żyłoby pod /osl/v2/, podczas gdy /osl/ dalej serwuje kontrakt v1 przez co najmniej dwie kolejne wersje minor. Endpointy MOGĄ dodawać opcjonalne pola odpowiedzi w obrębie v1.x; klienci MUSZĄ ignorować nierozpoznane pola.