Reduce Orbit API page to a pointer at the generated reference
What does this MR do and why?
Removes the duplicated endpoint reference and points readers at the interactive API reference instead. https://docs.gitlab.com/api/orbit/ was hand-maintained and had drifted behind the actual API surface. Orbit's six consumer-facing endpoints are now generated from their Grape source into doc/api/openapi/openapi_v3.yaml, so the same six endpoints ended up documented twice, by two different mechanisms, and the manual copy was going stale.
I checked endpoint coverage and all six endpoints on the manual page are present in the generated spec, and the generated spec adds none the page didn't have. Five further /orbit/* endpoints stay hidden from the spec and were undocumented on the page, so they're unaffected.
The generated spec carries method, path, summary, description, and request parameters, nothing else. This page keeps only what the spec can't express:
- Guidance to prefer
POST /api/v4/orbit/query/:nameoverPOST /api/v4/orbit/queryfor programmatic consumers: a named query's structure lives on the server, so it can't drift from the DSL grammar or ontology. - The query templates caveat:
raw_queryrenders per-user because identity values resolve server-side from request credentials, so templates must not be cached or shared across users; placeholders hold server-declared example values that need replacing before execution. - The five worked query DSL examples (search, traversal, aggregation, neighbors, path finding). These are the only worked examples of the Orbit query DSL in the repo.
- That
GET /api/v4/orbit/statusalways returns200 OKregardless of access or service health, plus thesystem: nullno-access response shape.
Important:
- Response documentation is thinner for now: the generated operations declare only
200and400descriptions, with no response bodies or schemas, so the response attribute tables the page used to carry are gone without a full equivalent in the reference yet. This is an accepted limitation, tracked at #624037. - A documented parameter that never existed: the page documented a
query_typerequest attribute onPOST /api/v4/orbit/query("Onlyjsonis supported").ee/lib/api/orbit/data.rbdoesn't declare it, so Grape drops it and the endpoint ignores it. This MR removes that row. - The deep link format will need updating later: the page links to
https://api.gitlab.com/rest/#tag/orbit. Once a second spec is published on the API reference, it will prefix every hash with the document slug, making the correct form#gitlab/tag/orbit.
References
Resolves: #624038 (closed)
Part of: gitlab-org/quality#428 (closed)
Screenshots or screen recordings
How to set up and validate locally
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.