Skip to content

Aligning REST to GitLab version instead

I propose we no longer have a distinct version for the REST-based API

Problem

  1. We are accumulating a lot of deprecations that are not actioned because we don't have a v5 API. Thi is a problem because there is code that we have to maintain to support these deprecated endpoints.
List of api deprecations awaiting v5 
$ git grep -i "#.*v5" lib
lib/api/entities/application_setting.rb:      # TODO: Once we rename the columns, we have to swap this around and keep supporting the old names until v5.
lib/api/entities/application_setting.rb:      # support legacy names, can be removed in v5
lib/api/entities/ci/job.rb:        # artifacts_file is included in job_artifacts, but kept for backward compatibility (remove in api/v5)
lib/api/entities/ci/runner.rb:        # TODO Remove in v5 in favor of `paused` for REST calls, see https://gitlab.com/gitlab-org/gitlab/-/issues/375709
lib/api/entities/ci/runner.rb:        # TODO Remove in v5 in favor of `status` for REST calls, see https://gitlab.com/gitlab-org/gitlab/-/issues/375709
lib/api/entities/project.rb:      # TODO: remove in API v5, replaced by *_access_level
lib/api/helpers/projects_helpers.rb:        # TODO: remove in API v5, replaced by *_access_level
lib/api/helpers/projects_helpers.rb:          # TODO: remove in API v5, replaced by *_access_level
lib/api/integrations.rb:    # The support for `:id/services` can be dropped if we create an API V5.
lib/api/settings.rb:      optional :password_authentication_enabled, type: Boolean, desc: 'Flag indicating if password authentication is enabled for the web interface' # support legacy names, can be removed in v5
lib/api/settings.rb:      optional :signin_enabled, type: Boolean, desc: 'Flag indicating if password authentication is enabled for the web interface' # support legacy names, can be removed in v5
lib/api/settings.rb:      optional :allow_local_requests_from_hooks_and_services, type: Boolean, desc: 'Deprecated: Use :allow_local_requests_from_web_hooks_and_services instead. Allow requests to the local network from hooks and services.' # support legacy names, can be removed in v5
lib/api/settings.rb:      # support legacy names, can be removed in v5
lib/api/settings.rb:      # support legacy names, can be removed in v5
lib/api/settings.rb:      # support legacy names, can be removed in v5
lib/api/settings.rb:      # support legacy names, can be removed in v5
lib/api/settings.rb:      # TODO: Once we rename the columns, we have to swap this around and keep supporting the old names until v5.
  1. Additionally, we see confusion from team members. For example, we see API removals scheduled for %17.0 (e.g data/deprecations/15-7-deprecate-api-v4-runner-registration-token-reset-endpoints.yml), which contradicts https://docs.gitlab.com/ee/api/index.html#compatibility-guidelines.

Proposal

There are three parts to this proposal.

1. Aligning to GitLab version

We align API support around GitLab Major releases, e.g. v16. We no longer have separate v5

We start by introducing /api/-/* initially as a copy of API v4. Subsequently, we remove /api/v4/* at GitLab v17.0, or GitLab 18.0.

2. Support policy

This part is dependent on part 1 above

We will only allow API compatibility to be broken at major versions.

However, we should only break API compatibility only if absolutely required. In other words, we keep API compatibility for most major versions.

3. Keeping older versions

This part can also be achieved with v4, v5 as well

We utilize headers to allow users to opt back to older versions of API endpoints

In 16.X:

  1. Users going to /api/v4/* get legacy_v4 api
  2. Users going to /api/-/* get v16 api
  3. Users going to /api/-/* with GitLab-API-Version: legacy_v4 get legacy_v4 api
  4. Users going to /api/-/* with GitLab-API-Version: v16 get v16 api

In 17.X:

(Legacy v4 removed)

  1. Users going to /api/v4/* get 404
  2. Users going to /api/-/* get v17 api
  3. Users going to /api/-/* with GitLab-API-Version: legacy_v4 get 404
  4. Users going to /api/-/* with GitLab-API-Version: v16 get v16 api
  5. Users going to /api/-/* with GitLab-API-Version: v17 get v17 api

In 18.X:

(16.X API removed)

  1. Users going to /api/v4/* get 404
  2. Users going to /api/-/* get v18 api
  3. Users going to /api/-/* with GitLab-API-Version: legacy_v4 get 404
  4. Users going to /api/-/* with GitLab-API-Version: v16 get 404
  5. Users going to /api/-/* with GitLab-API-Version: v17 get v17 api
  6. Users going to /api/-/* with GitLab-API-Version: v18 get v18 api

References

https://docs.gitlab.com/ee/api/index.html#compatibility-guidelines

See https://docs.gitlab.com/ee/api/graphql/#deprecation-and-removal-process on how GraphQL handles deprecations and removals

Edited by Thong Kuah