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:

  1. Guidance to prefer POST /api/v4/orbit/query/:name over POST /api/v4/orbit/query for programmatic consumers: a named query's structure lives on the server, so it can't drift from the DSL grammar or ontology.
  2. The query templates caveat: raw_query renders 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.
  3. 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.
  4. That GET /api/v4/orbit/status always returns 200 OK regardless of access or service health, plus the system: null no-access response shape.

Important:

  1. Response documentation is thinner for now: the generated operations declare only 200 and 400 descriptions, 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.
  2. A documented parameter that never existed: the page documented a query_type request attribute on POST /api/v4/orbit/query ("Only json is supported"). ee/lib/api/orbit/data.rb doesn't declare it, so Grape drops it and the endpoint ignores it. This MR removes that row.
  3. 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.

Edited by Alberto Bignotti

Merge request reports

Loading
Loading