## The problem GitLab has a REST API. This is a way for other programs to talk to GitLab automatically, for example to create a project or list issues, without a person clicking through the website. Right now, this API is documented in two separate places at the same time. The first is a set of 247 pages that people wrote by hand. They live in a folder called `doc/api/` inside the `gitlab-org/gitlab` project. The second is a website that gets built automatically, at https://api.gitlab.com/rest. Nobody writes this one by hand. A program builds it from a file called an OpenAPI specification (found at `doc/api/openapi/openapi_v3.yaml`). That file, in turn, is built from the underlying code that defines the API. The plan is to delete the 247 hand-written pages, so there is only one place left to maintain. Before that can happen, everything useful on those pages has to be moved into the underlying code, because that is where the automatically-built website gets its content. If something exists only on a hand-written page, it is lost the moment that page is deleted. The work is being done one part at a time. Already finished: a short introduction paragraph for each area of the API, and a one-line summary for each of the 1,738 individual API operations. Currently in progress: writing a proper description for each parameter, which is a piece of information you can send to an API operation. Not started: recording which paid subscription level each operation needs, and working out what to do with everything else the hand-written pages contain. ## What has to be true before the pages can be deleted | What | Where it lives now | State | |---|---|---| | Introduction for each API area | Content files in the repository | Done. 168 areas | | One-line summary for each operation | The code that defines the API | Done. 1,738 operations | | Description of each request parameter | The code that defines the API | In progress | | Which paid tier each operation needs | Not recorded anywhere yet | Not started | | Everything else the pages hold | Only on the hand-written pages | Not scoped. The largest risk | ## Why this is a separate epic Two other epics already exist that are related to this work, but neither one covers this job. The first, [REST API Docs Production Readiness and Public Beta Launch](https://gitlab.com/groups/gitlab-org/quality/-/epics/402) (due 2026-10-30), says plainly in its own scope that retiring the old hand-written pages, finishing the page redirects, and declaring the new site generally available are all out of scope for it. The second, [REST API Docs Post-GA Improvements](https://gitlab.com/groups/gitlab-org/quality/-/epics/414), covers work that happens after that launch. So nobody currently owns the job that sits in between those two: making the automatically-built website complete enough that the hand-written pages can be safely deleted. That in-between job is what this epic is for. ## The five pieces of work | Area | What it covers | Rows to review | |---|---|---| | [Conditional requirements](https://gitlab.com/gitlab-org/gitlab/-/issues/627785) | Parameter notes written in the wrong column, where the tooling cannot read them | 112 | | [Endpoint tier](https://gitlab.com/gitlab-org/gitlab/-/issues/627786) | Confirming which paid tier each paid-only operation needs | 370 | | [Area introductions](https://gitlab.com/gitlab-org/gitlab/-/issues/627787) | API areas still showing generated placeholder text | 12 | | [Missing from the specification](https://gitlab.com/gitlab-org/gitlab/-/issues/627788) | Endpoints the pages document that the generated website does not have | 319 | | [Content with no home](https://gitlab.com/gitlab-org/gitlab/-/issues/627789) | Prerequisites, warnings, caveats and sections that have nowhere to go yet | 1,299 | Each area above links to its issue. Each issue links to its own tab in a shared spreadsheet, and the parts within it are set out as separate comments on that issue. ## Assumptions - The row counts above come from an automated comparison of the hand-written pages against the generated specification. Two of the five areas turned up problems in work that was believed already finished, so these counts should be treated as things to confirm, not as a fixed list of defects. - Several of the pages involved are owned by writers who have not been consulted yet. Any change to one of those pages needs its owner's approval before it can be merged. - The machine-generated GraphQL reference under `doc/api/graphql/reference/` is excluded from every count in this epic.