Skip to content

Start v5 API

Background

https://docs.gitlab.com/ee/api/README.html#compatibility-guidelines states that:

The HTTP API is versioned using a single number, the current one being 4. This number symbolizes the same as the major version number as described by SemVer. This mean that backward incompatible changes will require this version number to change. However, the minor version is not explicit. This allows for a stable API endpoint, but also means new features can be added to the API in the same version number.

This effectively means that API backwards incompatible changes planned for %13.0 - such as !30580 (closed) - will have to wait for v5.

Problem

We have been on API v4 for a number of major releases now and we are gathering a growing number of deprecations which we cannot remove from APIv4.

Proposal

I think we are being stuck on the requirement that v5 API should be graphql compatibility layer. Here's what I propose to break the deadlock:

  1. Start work on v5 API. It is a straight copy v4 API minus all deprecated attributes and endpoints.
    • Design goal: For endpoints not marked as deprecated, changes in API v4 is automatically present in API v5
    • Design goal: For endpoints marked as deprecated, or endpoints where attributes are deprecated in v4, developer has to manually update v5, if any.
  2. When v5 API is ready, we deprecate v4 API. No new updates will be allowed to v4 except for security updates
  3. Next major milestone (or two major milestones after), we remove v4 API.
  4. Start work on v6 API. It is GraphQL + compatibility layer.
  5. When v6 API is ready, we deprecate v5 API.

Further details

But then the succeeding paragraph says:

New features and bug fixes are released in tandem with a new GitLab, and apart from incidental patch and security releases, are released on the 22nd of each month. Backward incompatible changes (e.g. endpoints removal, parameters removal etc.), as well as removal of entire API versions are done in tandem with a major point release of GitLab itself

See also https://gitlab.slack.com/archives/CJHPLRTRD/p1588322277101400 (internal slack thread)

Edited by Thong Kuah