REST API

通过极狐GitLab REST API 自动化工作流程并构建集成：

1. 创建自定义工具，以便在不进行手动干预的情况下大规模管理极狐GitLab 资源。
2. 通过将极狐GitLab 数据直接集成到应用程序中来改善协作。
3. 精确地管理多个项目的 CI/CD 流程。
4. 以编程方式控制用户访问，以在整个组织中保持一致的权限。

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

发起 REST API 请求#

要发起 REST API 请求：

1. 使用 REST API 客户端向 API 端点提交请求。
2. 极狐GitLab 实例响应请求，并返回状态码以及（如果适用）请求的数据。状态码指示请求的结果，在排除故障时很有用。

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

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

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

shell
curl "https://gitlab.example.com/api/v4/projects"

访问某些端点需要身份验证。有关更多信息，请参阅身份验证。

速率限制#

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

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

响应格式#

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

请求要求#

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

请求负载#

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

• 查询字符串：

  shell
  curl --request POST "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>" "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" \
"https://gitlab.example.com/api/v4/some_endpoint"

hash#

override_params 是一种 hash 类型的参数：

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

哈希数组#

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

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

在 ISO 8601 日期中编码 +#

如果需要在查询参数中包含 +，可能需要使用 %2B，因为根据 W3 推荐，+ 会被解释为一个空格。例如，在 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）。

重定向#

在路径更改之后，REST API 可能会响应一条消息，指出端点已移动。此时，请使用 Location 头中指定的端点。

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

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

响应为：

plaintext
...
< Location: http://gitlab.example.com/api/v4/projects/81
...
This resource has been moved permanently to https://gitlab.example.com/api/v4/projects/81

分页#

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

1. 基于偏移量的分页。默认方法，适用于除 users 端点外的所有端点。在极狐GitLab 16.5 及更高版本中，users 端点不再支持。
2. 基于键集的分页。

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

基于偏移量的分页#

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

在以下示例中，我们每页列出 50 个命名空间：

shell
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "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 --head --header "PRIVATE-TOKEN: <your_access_token>" "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>" "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，排除了已检索的记录。

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

shell
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "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，排除了已检索的记录。

过滤器的类型取决于使用的 order_by 选项，我们可以有多个附加过滤器。

当集合的末尾到达且没有其他记录可检索时，Link 头消失，结果数组为空。

您应该仅使用给定的链接来检索下一页，而不是构建自己的 URL。除了显示的头之外，我们不公开其他分页头。

支持的资源#

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

分页响应头#

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

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

版本控制和弃用#

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

1. 次要版本不是显式的，这允许稳定的 API 端点。
2. 新功能在同一版本号中添加到 API 中。
3. 主要的 API 版本更改和整个 API 版本的移除与极狐GitLab 的主要版本发布同步进行。
4. 文档中注明了版本之间的所有弃用和更改。

以下内容不在弃用过程中，可以随时删除而不另行通知：

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