Introduce lifecycle annotations for REST APIs and expand annotations for GraphQL
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
From the decision made at the FY26Q1 Tech Summit "Rethink our approach to maintaining our APIs (REST + GraphQL)" session -- documented in https://docs.google.com/document/d/1VNB3ivS9aCJc-fck1TLP48pzFYRsEPASLijn9ufXctY/edit?tab=t.2fcx3kdhhtj#bookmark=id.djz9l4fdc97u:
We should establish clear lifecycle guidelines for APIs
- Levels, e.g. internal, experimental, beta, stable, etc.
- How to introduce new API types/fields/endpoints, both for non-GA features, as well as iteration on GA features. E.g., are all new fields introduced as internal/experimental by default
- How to deprecate things - what is the lifecycle.
Introduction
GitLab's REST APIs have no concept of a lifecycle. Once an API is introduced, it is considered stable. This makes experimentation and customer-consultation on API design very difficult to do as APIs, fields and parameters can only be introduced once and thereafter considered stable for the long-term.
Lifecycle Annotations
As a means of risk management, we should move to gradually introducing changes to the API, to ensure that they fit our own needs, as well as those of our customers, and that they can scale, are observable, predictable and easy-to-understand.
This proposal sets our 5 lifecycle annotations which should be applied to all parameters, fields and REST endpoints in the application. They are:
| Lifecycle Stage | Description | Stability Guarrentees | Opt-In? | Documentation |
|---|---|---|---|---|
internal |
The endpoint/field/parameter is internal to GitLab and should not be used by customers. | None | n/a | None |
experimental |
The endpoint/field/parameter is experimental and should be used with a high degree of caution by customers, although feedback is welcome. | None | Opt-In | None |
beta |
The endpoint/field/parameter is beta and should be used with caution by customers, although feedback is welcome. | Current Major only | Opt-In (?) | beta.docs.gitlab.com |
stable |
The endpoint/field/parameter is stable. | Extended | docs.gitlab.com | |
deprecated |
The endpoint is EOL, but usage should be avoided | Limited | docs.gitlab.com |
Please note that this is a first proposal, and these attributes are subject to change.