• REST API
• GraphQL API
• 兼容性指南
  • 当前状态
• 如何使用 API
  • 有效的 API 请求
  • 公开 HTTP 响应头的 API 请求
  • 包含退出码的 API 请求
• 验证
  • OAuth2 令牌
  • 个人/项目/群组访问令牌
  • 会话 cookie
  • 模拟令牌
    • 禁用模拟
  • Sudo
• 状态码
• 分页
  • Offset-based 分页
    • 分页 Link header
    • 其它分页 headers
  • Keyset-based 分页
  • 分页响应 header
• 路径参数
• 命名空间路径编码
• 文件路径、分支和标签名称编码
• 请求负载
• 编码 array 和 hash 类型的 API 参数
  • array
  • hash
  • 哈希数组
• id vs iid
• 数据验证和错误报告
• 未知路由
• 在 ISO 8601 日期中编码 +
• 速率限制
• 内容类型

API 文档

使用 GitLab API 自动化极狐GitLab。

REST API

极狐GitLab 中提供了 REST API。 使用说明如下。

有关示例，请参阅如何使用 API。

GraphQL API

极狐GitLab 中提供了 GraphQL API。

使用 GraphQL，您可以只针对您需要的内容发出 API 请求，并且默认情况下它是版本化的。

GraphQL 与当前的 v4 REST API 共存。如果有 v5 API，应该是 GraphQL 之上的兼容层。

兼容性指南

HTTP API 使用单个数字进行版本控制，目前为 4。此数字表示主要版本号，如 SemVer 所述。 因此，向后不兼容的更改需要更改此版本号。

次要版本不是显式的，它允许稳定的 API 端点。可以在相同版本号的 API 中添加新功能。

当前状态

只有 API 版本 v4 可用。

如何使用 API

API 请求必须同时包含 api 和 API 版本。API 版本在 lib/api.rb 中定义。 例如，v4 API 的根目录位于 /api/v4。

有效的 API 请求

以下是对虚构的 gitlab.example.com 端点的请求的基本示例：

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

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

公开 HTTP 响应头的 API 请求

如果要公开 HTTP 响应头，请使用 --include 选项：

curl --include "https://gitlab.example.com/api/v4/projects"
HTTP/2 200
...

此请求可以帮助您调查意外响应。

包含退出码的 API 请求

如果要公开 HTTP 退出码，请包含 --fail 选项：

curl --fail "https://gitlab.example.com/api/v4/does-not-exist"
curl: (22) The requested URL returned error: 404

HTTP 退出码可以帮助您诊断 REST 请求的成功或失败。

验证

大多数 API 请求都需要身份验证，或者仅在未提供身份验证时才返回公共数据。当不需要身份验证时，每个端点的文档都会说明这一点。例如，/projects/:id 端点不需要身份验证。

您可以通过多种方式使用 GitLab API 进行身份验证：

• OAuth2 令牌
• 个人访问令牌
• 项目访问令牌
• 群组访问令牌
• 会话 cookie
• 极狐GitLab CI/CD 作业令牌 （仅限特定端点）

项目访问令牌受以下支持：

• 私有化部署版的免费版及更高版本。
• SaaS 版的专业版及更高版本。

如果您是管理员，您或您的应用程序可以作为特定用户进行身份验证。 请使用：

• 模拟令牌
• Sudo

如果身份验证信息无效或丢失，系统会返回一条错误消息，状态码为 401：

{
  "message": "401 Unauthorized"
}

OAuth2 令牌

您可以使用 OAuth2 令牌，通过在 access_token 参数或 Authorization header 中传递 API 来进行身份验证。

在参数中使用 OAuth2 令牌的示例：

curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"

在 header 中使用 OAuth2 令牌的示例：

curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects"

个人/项目/群组访问令牌

您可以通过将访问令牌传递给 private_token 参数或 PRIVATE-TOKEN header，来使用访问令牌对 API 进行身份验证。

在参数中使用个人、项目或群组访问令牌的示例：

curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"

在 header 中使用个人、项目或群组访问令牌的示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"

您还可以将个人、项目或群组访问令牌与符合 OAuth 的 header 一起使用：

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"

会话 cookie

登录到极狐GitLab 主应用程序会设置一个 _gitlab_session cookie。API 使用此 cookie 进行身份验证（如果存在）。不支持使用 API 生成新的会话 cookie。

这种身份验证方法的主要用户是极狐GitLab 本身的 Web 前端。Web 前端可以使用 API 作为经过身份验证的用户来获取项目列表，而无需显式传递访问令牌。

模拟令牌

模拟令牌是个人访问令牌的一种。 它们只能由管理员创建，并用于特定用户使用 API 时进行身份验证。

使用模拟令牌替代：

• 用户的密码或他们的个人访问令牌之一。
• Sudo 功能。用户或管理员的密码或令牌可能不为人所知，或者可能会随着时间而改变。

模拟令牌的使用与常规个人访问令牌完全相同，可以在 private_token 参数或 PRIVATE-TOKEN header 中传递。

禁用模拟

默认情况下，模拟已启用。要禁用模拟：

Omnibus 安装实例

1. 编辑 /etc/gitlab/gitlab.rb 文件：

   gitlab_rails['impersonation_enabled'] = false
   

2. 保存文件，然后重新配置极狐GitLab，使更改生效。

要重新启用模拟，请删除此配置，然后重新配置极狐GitLab。

源安装实例

1. 编辑 config/gitlab.yml 文件：

   gitlab:
     impersonation_enabled: false
   

2. 保存文件，然后重启极狐GitLab，使更改生效。

要重新启用模拟，请删除此配置，然后重新启动极狐GitLab。

Sudo

您使用具有 sudo 范围的 OAuth 或个人访问令牌作为管理员进行身份验证时，所有 API 请求都支持您像是其它用户一样执行 API 请求。API 请求以模拟用户的权限执行。

作为管理员，通过使用查询字符串，或带有您要执行操作的用户的 ID，或用户名（不区分大小写）的 header 传递 sudo 参数。如果作为 header 传递，header 名称必须是 Sudo。

如果提供了非管理访问令牌，系统将返回状态代码为 403 的错误消息：

{
  "message": "403 Forbidden - Must be admin to use sudo"
}

如果提供了没有 sudo 范围的访问令牌，则会返回错误消息，状态码为 403：

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token.",
  "scope": "sudo"
}

如果找不到 sudo 用户 ID 或用户名，则返回错误消息，状态码为 404：

{
  "message": "404 User with ID or username '123' Not Found"
}

有效 API 请求，和使用 cURL 以及 sudo 的请求的示例，提供用户名：

GET /projects?private_token=<your_access_token>&sudo=username

curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"

有效 API 请求，和使用 cURL 以及 sudo 的请求的示例，提供 ID：

GET /projects?private_token=<your_access_token>&sudo=23

curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"

状态码

API 旨在根据上下文和操作返回不同的状态码。如果请求导致错误，您可以深入了解问题所在。

下表概述了 API 函数的一般行为方式。

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

分页

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

• Offset-based 分页。这是默认方法，适用于所有端点。
• Keyset-based 分页。添加到选定的端点，但正在逐步推出。

对于大型集合，出于性能原因，我们建议使用 Keyset-based 分页（如果可用）而不是 Offset-based 分页。

Offset-based 分页

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

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

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

分页 Link header

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

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

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/2 200 OK
cache-control: no-cache
content-length: 1103
content-type: application/json
date: Mon, 18 Jan 2016 09:43:18 GMT
link: <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"
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

其它分页 headers

返回以下更多其它分页 headers：

Keyset-based 分页

Keyset-based 分页允许更有效地检索页面，并且与 Offset-based 分页相比，运行时独立于集合的大小。

此方法由以下参数控制。order_by 和 sort 为必填项。

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

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"

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

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 个群组，使用 Keyset-based 分页，按 name 升序排列：

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"

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

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 header 不存在并且结果数组为空。

我们建议仅使用给定的链接来检索下一页，而不是构建您自己的 URL。除了显示的 header 外，我们不暴露更多的分页 header。

仅选定资源和排序选项支持 Keyset-based 的分页：

分页响应 header

出于性能原因，如果查询返回超过 10,000 条记录，系统不会返回以下 header：

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

路径参数

如果端点具有路径参数，则文档会使用前面的冒号显示它们。

例如：

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://gitlab.example.com/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 或项目的设置中找到，位于 通用 > 高级 > 更改路径 下。

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

如果文件路径、分支或标签包含 /，请确保它是 URL 编码的。

例如，/ 由 %2F 表示：

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

请求负载

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 错误消息。可以通过使用负载主体来解决。

编码 array 和 hash 类型的 API 参数

您可以使用 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://gitlab.example.com/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://gitlab.example.com/api/v4/projects/import"

哈希数组

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

curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"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"

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://gitlab.example.com/api/v4/projects/169/pipeline"

id vs iid

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

• 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 获取。有关使用哪个字段的指导，请参阅特定资源的文档。

数据验证和错误报告

使用 API 时，您可能会遇到验证错误，在这种情况下，API 会返回 HTTP 400 错误。

此类错误出现在以下情况：

• 缺少 API 请求的必需属性（例如，未给出议题的标题）。
• 属性未通过验证（例如，用户 bio 太长）。

当缺少某个属性时，您会收到如下信息：

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"
}

在 ISO 8601 日期中编码 +

如果您需要在查询参数中包含 +，则可能需要使用 %2B，因为 W3 建议导致 + 被解释为空格。例如，在 ISO 8601 日期中，您可能希望包含 ISO 8601 格式的特定时间，例如：

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

查询参数的正确编码是：

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

速率限制

有关速率限制设置的管理员文档，请参阅 速率限制。

内容类型

GitLab API 默认支持 application/json 内容类型，尽管一些 API 端点也支持 text/plain。

在 13.10 及更高版本中，API 端点默认不支持 text/plain，除非明确记录。