From f1314c5ee53dafecd8a0278f6faefbc40bfdd149 Mon Sep 17 00:00:00 2001 From: Zeger-Jan van de Weg Date: Tue, 24 Apr 2018 16:26:19 +0200 Subject: [PATCH] Document compatibility process for the HTTP API GitLab lacked formal documentation around our API, how the versioning worked and to the numbers meant. Fixes https://gitlab.com/gitlab-org/gitlab-ce/issues/22693 --- doc/api/README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/api/README.md b/doc/api/README.md index ae4481b400e..66e1df41cf6 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -85,6 +85,29 @@ have been resolved to our satisfaction by the relicensing of the reference implementations under MIT, and the use of the OWF license for the GraphQL specification. +## Compatibility Guidelines + +The HTTP API is versioned using a single number, the current one being 4. This +number symbolises the same as the major version number as described by +[SemVer](https://semver.org/). 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. + +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 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. All deprecations and changes +between two versions should be listed in the documentation. For the changes +between v3 and v4; please read the [v3 to v4 documentation](v3_to_v4.md) + +#### Current status + +Currently two API versions are available, v3 and v4. v3 is deprecated and +will soon be removed. Deletion is scheduled for +[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-ce/issues/36819). + ## Basic usage API requests should be prefixed with `api` and the API version. The API version