REST API

使用 极狐GitLab REST API 自动化你的工作流程并构建集成：

• 创建自定义工具来大规模管理你的 极狐GitLab 资源，无需手动干预。
• 通过将 极狐GitLab 数据直接集成到你的应用程序中来改善协作。
• 精确管理跨多个项目的 CI/CD 流程。
• 通过编程方式控制用户访问，以维护整个组织的一致性权限。

REST API 使用标准的 HTTP 方法和 JSON 数据格式，与你现有的工具和系统兼容。

发起 REST API 请求#

要发起 REST API 请求：

• 使用 REST API 客户端向 API 端点提交请求。
• 极狐GitLab 实例响应请求。它返回一个状态码，如果适用，还会返回请求的数据。状态码表示请求的结果，在排查问题时很有用。

REST API 请求必须以根端点和路径开头。

• 根端点是 极狐GitLab 主机名。
• 路径必须以 /api/v4（v4 表示 API 版本）开头。

在以下示例中，API 请求检索 极狐GitLab 主机 gitlab.example.com 上的所有项目列表：

shell
curl --request GET \
  --url "https://gitlab.example.com/api/v4/projects"

某些端点的访问需要身份认证。更多信息，请参见身份认证。

速率限制#

REST API 请求受速率限制设置约束。这些设置降低了 极狐GitLab 实例过载的风险。

• 详情请参见速率限制。
• 有关 JihuLab.com 使用的速率限制设置的详细信息，请参见 JihuLab.com 特定的速率限制。

响应格式#

REST API 响应以 JSON 格式返回。某些 API 端点也支持纯文本格式。要确认端点支持哪种内容类型，请参见 REST API 资源。

请求要求#

某些 REST API 请求有特定要求，包括所用的数据格式和编码。

请求负载#

API 请求可以使用作为查询字符串或作为负载体发送的参数。GET 请求通常发送查询字符串，而 PUT 或 POST 请求通常发送负载体：

• 查询字符串：

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

• 请求负载（JSON）：

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

URL 编码的查询字符串有长度限制。过大的请求会导致 414 Request-URI Too Large 错误消息。这可以通过改用负载体来解决。

路径参数#

如果端点有路径参数，文档会以冒号作为前缀显示它们。

例如：

plaintext
DELETE /projects/:id/share/:group_id

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

然后，对于 ID 为 5 的项目和群组 ID 为 17 的 cURL 请求为：

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/share/17"

必须遵循需要 URL 编码的路径参数。如果不这样做，它将不匹配 API 端点并返回 404。如果 API 前面有东西（例如 Apache），请确保它不会解码 URL 编码的路径参数。

id 与 iid#

某些 API 资源有两个名称相似的字段。例如，议题、合并请求和项目里程碑。这些字段是：

• id：在所有项目间唯一的 ID。
• iid：额外的、内部的 ID（在 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 获取。有关使用哪个字段的指导，请查看特定资源的文档。

编码#

在进行 REST API 请求时，某些内容必须进行编码以处理特殊字符和数据结构。

命名空间路径#

如果使用命名空间 API 请求，请确保 NAMESPACE/PROJECT_PATH 经过 URL 编码。

例如，/ 由 %2F 表示：

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

项目的路径不一定与其名称相同。项目的路径可在项目的 URL 中或项目的设置中找到，在通用 > 高级 > 更改路径中。

文件路径、分支和标签名称#

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

例如，/ 由 %2F 表示：

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

数组和哈希类型#

你可以使用 array 和 hash 类型参数请求 API：

array#

import_sources 是一个 array 类型的参数：

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  -d "import_sources[]=github" \
  -d "import_sources[]=bitbucket" \
  --url "https://gitlab.example.com/api/v4/some_endpoint"

hash#

override_params 是一个 hash 类型的参数：

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --form "namespace=email" \
4  --form "path=impapi" \
5  --form "file=@/path/to/somefile.txt" \
6  --form "override_params[visibility]=private" \
7  --form "override_params[some_other_param]=some_value" \
8  --url "https://gitlab.example.com/api/v4/projects/import"

哈希数组#

variables 是一个 array 类型的参数，包含哈希键值对 [{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]：

shell
1curl --globoff --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --url "https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world"
4
5curl --request POST \
6  --header "PRIVATE-TOKEN: <your_access_token>" \
7  --header "Content-Type: application/json" \
8  --data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \
9  --url "https://gitlab.example.com/api/v4/projects/169/pipeline"

ISO 8601 日期中的 + 编码#

如果你需要在查询参数中包含 +，由于 W3 推荐会导致 + 被解释为空格，你可能需要使用 %2B 代替。例如，在 ISO 8601 日期中，你可能想包含特定的时间，如：

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

查询参数的正确编码是：

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

评估响应#

在某些情况下，API 响应可能不如你预期。问题可能包括空值和重定向。如果你在响应中收到数字状态码，请参见状态码。

null 与 false#

在 API 响应中，某些布尔字段可能有 null 值。一个 null 布尔值没有默认值，既不是 true 也不是 false。极狐GitLab 将布尔字段中的 null 值视为与 false 相同。

在布尔参数中，你应该只设置 true 或 false 值（而不是 null）。

重定向#

版本历史

• 在 极狐GitLab 16.4 中引入，通过功能标志 api_redirect_moved_projects。默认禁用。
• 在 极狐GitLab 16.7 中 GA。功能标志 api_redirect_moved_projects 已移除。

路径变更后，REST API 可能会响应一条消息，指出端点已移动。发生这种情况时，请使用 Location 头中指定的端点。

项目移动到不同路径的示例：

shell
curl --request GET \
  --verbose \
  --url "https://gitlab.example.com/api/v4/projects/gitlab-org%2Fold-path-project"

响应为：

plaintext
...
< Location: http://gitlab.example.com/api/v4/projects/81
...
此资源已永久移动到 https://gitlab.example.com/api/v4/projects/81

分页#

极狐GitLab 支持以下分页方法：

• 基于偏移的分页。默认方法，在除 极狐GitLab 16.5 及之后的 users 端点外的所有端点上都可用。
• 基于键集的分页。已添加到选定的端点，但正在逐步推出。

对于大型集合，出于性能原因，你应使用键集分页（当可用时）而不是偏移分页。

基于偏移的分页#

版本历史

• 在 极狐GitLab 16.5 中，users 端点的基于偏移分页已被弃用，并计划在 17.0 中移除。此更改是破坏性更改。请改为此端点使用基于键集的分页。
• 在 极狐GitLab 17.0 中，当请求的记录数大于 50,000 时，users 端点强制使用基于键集的分页。

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

以下示例每页列出 50 个命名空间：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/namespaces?per_page=50"

分页 Link 头#

每个响应都返回 Link 头。它们将 rel 设置为 prev、next、first 或 last，并包含相关的 URL。请务必使用这些链接，而不是生成你自己的 URL。

对于 JihuLab.com 用户，某些分页头可能不会返回。

以下 cURL 示例将每页输出限制为三个项目（per_page=3），并请求 ID 为 9 的项目中 ID 为 8 的议题的评论的第二页（page=2）：

shell
curl --request GET \
  --head \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"

响应为：

http
1HTTP/2 200 OK
2cache-control: no-cache
3content-length: 1103
4content-type: application/json
5date: Mon, 18 Jan 2016 09:43:18 GMT
6link: <https://gitlab.example.com/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"
7status: 200 OK
8vary: Origin
9x-next-page: 3
10x-page: 2
11x-per-page: 3
12x-prev-page: 1
13x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86
14x-runtime: 0.108688
15x-total: 8
16x-total-pages: 3

其他分页头#

极狐GitLab 还返回以下额外的分页头：

对于 JihuLab.com 用户，某些分页头可能不会返回。

基于键集的分页#

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

此方法由以下参数控制。order_by 和 sort 都是必填的。

以下示例每页列出 50 个项目，按 id 升序排列。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"

响应头包含指向下一页的链接。例如：

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

指向下一页的链接包含一个额外的过滤器 id_after=42，它排除了已检索的记录。

另一个示例，以下请求每页列出 50 个群组，使用键集分页按 name 升序排列：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc"

响应头包含指向下一页的链接：

http
HTTP/1.1 200 OK
...
Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next"
Status: 200 OK
...

指向下一页的链接包含一个额外的过滤器 cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9，它排除了已检索的记录。

X-NEXT-CURSOR 头包含用于检索下一页记录的光标值，而 X-PREV-CURSOR 头（如果可用）包含用于检索上一页的光标值。

过滤器的类型取决于所使用的 order_by 选项，而且你可以有多个额外的过滤器。

当到达集合末尾并且没有更多记录可检索时，Link 头将不存在，并且结果数组为空。

你应该只使用给定的链接来检索下一页，而不是构建自己的 URL。除了显示的头之外，不公开额外的分页头。

支持的资源#

仅部分资源和排序选项支持基于键集的分页：

分页响应头#

出于性能原因，如果查询返回超过 10,000 条记录，极狐GitLab 不会返回以下头：

• x-total。
• x-total-pages。
• rel="last" link

版本控制与弃用#

REST API 版本遵循语义化版本控制规范。主版本号是 4。向后不兼容的更改需要此版本号发生变化。

• 次要版本未明确标明，这允许稳定的 API 端点。
• 新功能会以相同的版本号添加到 API 中。
• API 主版本号的更改以及整个 API 版本的移除会与主要的 极狐GitLab 版本一起进行。
• 所有弃用和版本之间的更改都在文档中注明。

以下内容被排除在弃用流程之外，并且可能随时移除，恕不另行通知：

• 在 REST API 资源中被标记为实验性或 Beta 的元素。
• 功能标志后面且默认禁用的字段。

对于私有化部署，从企业版实例回退到社区版会导致破坏性更改。