API 文档

完整的 API 文档参考 Gitlab API docs：https://docs.gitlab.com/13.2/ee/api/README.html

主要的 GitLab API 是REST API。因此，本文档假定您了解 REST 的概念及知识。

可用的 API 资源

有关可用资源及其接口的列表，请参阅API 资源。

熟悉 GraphQL

GitLab中提供了GraphQL ，它将允许弃用控制器特定的接口。

GraphQL 具有许多优点：

我们避免维护两个不同的 API
API 的调用者只能请求他们需要的东西
版本已经默认

它将与当前的 v4 REST API 共存；如果我们有 v5 API，则它应该是 GraphQL 之上的兼容性层。

尽管 GraphQL 存在一些专利和许可问题，但通过 MIT 下的参考实现的重新许可以及 GraphQL 规范使用 OWF 许可证，我们已经满意得解决了这些问题。

兼容性指引

HTTP API 使用单个数字进行版本控制，当前版本为 4。此数字与SemVer描述的主要版本号相同，这意味着向后不兼容的更改将需要更改此版本号。但是，次要版本不明确。这可以实现稳定的 API 接口，但也意味着可以将新功能以相同的版本号添加到 API。

新功能和错误修复将与新的 GitLab 于每月 22 日发布一起发布，附带的修补程序和安全版本除外。向后不兼容的更改（例如，接口删除，参数删除等）以及整个 API 版本的删除与 GitLab 本身的主要版本一起进行，两个版本之间的所有弃用和更改都应在文档中列出。对于 v3 和 v4 之间的更改，请阅读v3 至 v4 文档。

当前版本

当前仅提供 API 版本 v4，v3 版本已在GitLab 11.0中移除。

基础用法

API 请求应以api和 API 版本为前缀，API 版本在lib/api.rb定义，例如，v4 API 的根位于/api/v4 。

使用 cURL 的有效 API 请求的示例：

curl "https://gitcode.net/api/v4/projects"

该 API 使用 JSON 序列化数据，您无需在 API URL 的末尾指定.json 。

认证

大多数 API 请求都需要身份验证，或者仅在不提供身份验证时才返回公共数据。对于不需要的情况，将在文档中针对每个接口进行提及，例如， /projects/:id接口。

我们建议使用以下方式来进行身份验证：

Personal access tokens

如果身份验证信息无效或被忽略，将返回一条状态码为401的错误消息：

{  "message":  "401 Unauthorized"  }

用户访问令牌

访问令牌可通过 private_token 参数或 Private-Token 头文件来进行API接口的验证。

在参数中使用个人访问令牌的示例：

curl "https://gitcode.net/api/v4/projects?private_token=<your_access_token>"

在头文件使用个人访问令牌的示例：

curl --header "Private-Token: <your_access_token>" "https://gitcode.net/api/v4/projects"

状态码

API 可以根据上下文和操作返回不同的状态码，如果请求导致错误，则调用者可以通过状态码了解出了什么问题。

下表概述了 API 函数的一般行为：

请求类型	说明
`GET`	访问一个或多个资源，并将结果作为 JSON 返回
`POST`	如果成功创建资源，则返回`201 Created` ，然后将新创建的资源作为 JSON 返回
`GET` / `PUT`	如果成功访问或修改了资源，则返回`200 OK` ，（修改后的）结果作为 JSON 返回
`DELETE`	如果资源已成功删除，则返回`204 No Content`

下表显示了 API 请求可能的返回码：

返回值	说明
`200 OK`	`GET` ， `PUT`或`DELETE`请求成功，资源本身作为 JSON 返回
`204 No Content`	服务器已成功满足请求，并且响应有效载荷主体中没有其他要发送的内容
`201 Created`	`POST`请求成功，资源作为 JSON 返回
`304 Not Modified`	指示自上次请求以来尚未修改资源
`400 Bad Request`	API 请求的必需属性丢失，例如，未提供问题标题
`401 Unauthorized`	用户未通过身份验证，有效的用户令牌是必需的
`403 Forbidden`	不允许该请求，例如，不允许用户删除项目
`404 Not Found`	无法访问资源，例如，找不到资源的 ID
`405 Method Not Allowed`	服务器不支持该请求
`409 Conflict`	已经存在冲突的资源，例如，使用已经存在的名称创建项目
`412`	表示请求被拒绝 `If-Unmodified-Since`尝试删除资源时提供了`If-Unmodified-Since`标头，则可能会发生这种情况
`422 Unprocessable`	无法处理该实体
`500 Server Error`	在处理请求时，服务器端出了问题

分页方法

我们支持两种分页方法：

基于偏移的分页，这是默认方法，并且在所有接口上都可用
基于键集的分页，已添加到选定的接口，但会逐步推出

对于大型集合，出于性能原因，我们建议键集分页（如果有）而不是偏移分页。

偏移分页

有时，返回的结果将跨越许多页面。列出资源时，可以传递以下参数：

参数	说明
`page`	页码（默认： `1` ）
`per_page`	每页要列出的项目数（默认： `20` ，最大： `100` ）

在下面的示例中，我们每页列出 50 个名称空间。

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/namespaces?per_page=50"

分页链接头

链接头随每个响应一起发送回去，它们的rel设置为 prev / next / first / last 并包含相关的 URL。请使用这些链接，而不是生成自己的 URL。

在下面的 cURL 调用例子中，我们限制输出到每页 3 项（ per_page=3 ），我们要求的第二页（ page=2的）评论与 ID 问题的8属于与 ID 项目8 ：

curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/projects/8/issues/8/notes?per_page=3&page=2"

响应将是：

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 1103
Content-Type: application/json
Date: Mon, 18 Jan 2020 09:43:18 GMT
Link: <https://gitcode.net/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
Status: 200 OK
Vary: Origin
X-Next-Page: 3
X-Page: 2
X-Per-Page: 3
X-Prev-Page: 1
X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86
X-Runtime: 0.108688
X-Total: 8
X-Total-Pages: 3

其他分页头

其他分页头信息也会发送回：

头信息	说明
`X-Total`	项目总数
`X-Total-Pages`	总页数
`X-Per-Page`	每页的项目数
`X-Page`	当前页面的索引（从 1 开始）
`X-Next-Page`	下一页的索引
`X-Prev-Page`	前一页的索引

注意：由于性能原因，自GitLab 11.8 起并在api_kaminari_count_with_limit 功能标志后面 ，如果资源数量大于 10,000，则X-Total和X-Total-Pages标头以及rel="last" Link将不存在响应头。

键集分页

键集分页可以更有效地检索页面，并且与基于偏移的分页相比，运行时与集合的大小无关。

此方法由以下参数控制：

参数	说明
`pagination`	`keyset` （启用键集分页）
`per_page`	每页要列出的项目数（默认： `20` ，最大： `100` ）

在下面的示例中，我们每页列出 50 个项目，并按id升序排列。

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"

响应头包括指向下一页的链接，例如：

HTTP/1.1 200 OK
...
Links: <https://gitcode.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
Link: <https://gitcode.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
Status: 200 OK
...

弃用： Links标题将在 GitLab 14.0 中删除，以符合W3C Link规范

指向下一页的链接包含一个附加过滤器id_after=42 ，该过滤器不包括我们已经检索到的记录。请注意，过滤器的类型取决于所使用的order_by选项，我们可能有多个过滤器。

当到达集合的末尾并且没有其他要检索的记录时，将没有Links头，并且结果数组为空。

我们建议仅使用给定的链接来检索下一页，而不要构建自己的 URL. 除了显示的标题外，我们不公开其他分页标题。

仅针对所选资源和订购选项支持基于键集的分页：

资源	排序
Projects	`order_by=id` only

路径参数

如果接口具有路径参数，则文档将在它们前面加上冒号。

例如：

DELETE /projects/:id/share/:group_id

:id路径参数需要替换为项目 ID，而:group_id需要替换为组织的 ID，冒号:不应包含在内。

因此，对 ID 为5 ，组 ID 为17的项目的 cURL 调用为：

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/projects/5/share/17"

注意： 必须遵循要求进行 URL 编码的路径参数。如果不是，它将与 API 接口不匹配并以 404 进行响应。如果 API 前面有某些内容（例如 Apache），请确保它不会对 URL 编码的路径参数进行解码。

命名空间路径编码

如果使用命名空间的 API 调用，请确保NAMESPACE/PROJECT_PATH是 URL 编码的。

例如， /由%2F表示：

GET /api/v4/projects/diaspora%2Fdiaspora

注意： 项目的路径不必与名称相同，可以在项目的 URL 或项目设置中的常规>高级>更改路径下找到项目的路径。

文件路径、分支、tag 编码

如果文件路径，分支或标记包含/ ，请确保其经过 URL 编码。

例如， /由%2F表示：

GET /api/v4/projects/1/repository/files/src%2FREADME-?ref=master
GET /api/v4/projects/1/branches/my%2Fbranch/commits
GET /api/v4/projects/1/repository/tags/my%2Ftag

请求有效载荷

API 请求可以使用作为查询字符串或有效载荷主体发送的参数。GET 请求通常发送查询字符串，而 PUT / POST 请求通常发送有效内容正文：

请求参数：

curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>"

请求有效载荷（JSON）：

curl --request POST --header "Content-Type: application/json" --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects"

URL 编码的查询字符串具有长度限制，请求太大将导致414 Request-URI Too Large错误消息，这可以通过使用有效载荷主体来解决。

Encoding API parameters of `array` and `hash` types

我们可以使用array和hash类型参数调用 API，如下所示：

`array`

import_sources是array类型的参数：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
-d "import_sources[]=github" \
-d "import_sources[]=bitbucket" \
https://gitcode.net/api/v4/some_endpoint

`hash`

override_params是hash类型的参数：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form "namespace=email" \
--form "path=impapi" \
--form "file=@/path/to/somefile.txt"
--form "override_params[visibility]=private" \
--form "override_params[some_other_param]=some_value" \
https://gitcode.net/api/v4/projects/import

hash 键对

variables是包含哈希键/值对[{ 'key' => 'UPLOAD_TO_S3', 'value' => 'true' }] array类型的参数：

curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitcode.net/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world"

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \
"https://gitcode.net/api/v4/projects/169/pipeline"

`id` vs `iid`

Some resources have two similarly-named fields. For example, issues, merge requests, and project milestones. The fields are:

id ：在所有项目中唯一的 ID.
iid ：在单个项目范围内唯一的附加内部 ID.

注意： iid显示在 Web UI 中.

如果资源具有iid字段和id字段，则通常使用iid字段代替id来获取资源。

例如，假设一个id: 42的项目有一个id: 46和iid: 5 ，在这种情况下：

检索问题的有效 API 调用是GET /projects/42/issues/5
检索问题的无效 API 调用是GET /projects/42/issues/46

注意： 并非所有具有iid字段的资源都由iid获取，有关使用哪个字段的指导，请参阅特定资源的文档。

数据验证及错误报告

使用 API时，您可能会遇到验证错误，在这种情况下，API 会以 HTTP 400状态进行回答。

这种错误在两种情况下出现：

API 请求的必需属性丢失，例如，未给出问题标题
属性未通过验证，例如，用户描述太长

当缺少属性时，您将获得类似以下内容的信息：

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
 "message":"400 (Bad request) \"title\" not given"
}

发生验证错误时，错误消息将有所不同。它们将包含验证错误的所有详细信息：

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
 "message": {
 "bio": [
 "is too long (maximum is 255 characters)"
 ]
 }
}

这使错误消息更加机器可读. 格式可以描述如下：

{  "message":  {  "<property-name>":  [  "<error-message>",  "<error-message>",  ...  ],  "<embed-entity>":  {  "<property-name>":  [  "<error-message>",  "<error-message>",  ...  ],  }  }  }

不存在的路由

当您尝试访问不存在的 API URL 时，您将收到 404 Not Found。

HTTP/1.1 404 Not Found
Content-Type: application/json
{
 "error": "404 Not Found"
}

Encoding `+` in ISO 8601 dates

如果需要在查询参数中包含+ ，则由于W3 建议会将+解释为空格，因此可能需要使用%2B来代替。例如，在一个 ISO 8601 日期中，您可能希望以"山区标准时间"传递时间，例如：

2017-10-17T23:11:13.000+05:30

The correct encoding for the query parameter would be:

2017-10-17T23:11:13.000%2B05:30

客户端

大多数流行的编程语言都有许多非官方的 GitLab API 客户端，访问GitLab 网站以获取完整列表。

频率限制

有关速率限制设置的管理员文档，请参阅速率限制，要查找 GitLab.com 专门使用的设置，请参阅GitLab.com 特定的速率限制。

GitCode / 帮助文档

api