diff options
author | Rémy Coutable <remy@rymai.me> | 2018-04-26 06:27:12 +0000 |
---|---|---|
committer | Rémy Coutable <remy@rymai.me> | 2018-04-26 06:27:12 +0000 |
commit | 928e45e7d3ac34d4b98bf0d8d57ca6c33e1e924f (patch) | |
tree | 0a55aab5f8183c444b93c3d03914e8c6c0fc98af /doc/api | |
parent | 55f07cc32e7684b21e0c1662c70128df14c6abf7 (diff) | |
parent | f1314c5ee53dafecd8a0278f6faefbc40bfdd149 (diff) | |
download | gitlab-ce-928e45e7d3ac34d4b98bf0d8d57ca6c33e1e924f.tar.gz |
Merge branch 'docs-zj-api-compat-docs' into 'master'
Document compatibility process for the HTTP API
Closes #22693
See merge request gitlab-org/gitlab-ce!18565
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/README.md | 23 |
1 files changed, 23 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 9879c667150..40071f1ed8b 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -86,6 +86,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 |