API Docs

原文：https://docs.gitlab.com/ee/api/README.html

• Available API resources
• SCIM
• Road to GraphQL
• Compatibility guidelines
  • Current status
• Basic usage
• Authentication
  • OAuth2 tokens
  • Personal/project access tokens
  • Session cookie
  • GitLab CI job token
  • Impersonation tokens
    • Disable impersonation
  • Sudo
• Status codes
• Pagination
  • Offset-based pagination
    • Pagination Link header
    • Other pagination headers
  • Keyset-based pagination
• Path parameters
• Namespaced path encoding
• File path, branches, and tags name encoding
• Request Payload
• Encoding API parameters of array and hash types
  • array
  • hash
  • Array of hashes
• id vs iid
• Data validation and error reporting
• Unknown route
• Encoding + in ISO 8601 dates
• Clients
• Rate limits

API Docs

通过简单而强大的 API 自动化 GitLab.

主要的 GitLab API 是REST API. 因此，本节中的文档假定您具有 REST 概念的知识.

Available API resources

有关可用资源及其端点的列表，请参阅API 资源 .

SCIM

GitLab.com Silver 和更高版本提供了SCIM API ， 该 API实现RFC7644 协议并提供/Users端点. 基本网址为： /api/scim/v2/groups/:group_path/Users/ .

Road to GraphQL

GitLab中提供了GraphQL ，它将允许弃用控制器特定的端点.

GraphQL 具有许多优点：

1. 我们避免维护两个不同的 API.
2. API 的调用者只能请求他们需要的东西.
3. 默认情况下为版本.

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

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

Compatibility guidelines

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

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

Current status

当前仅提供 API 版本 v4. v3 版本已在GitLab 11.0中删除.

Basic usage

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

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

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

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

Authentication

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

使用 GitLab API 进行身份验证的方法有几种：

1. OAuth2 tokens
2. Personal access tokens
3. Project access tokens
4. Session cookie
5. GitLab CI/CD job token （仅特定端点）

对于想要以特定用户身份向 API 进行身份验证的管理员，或者想要构建执行此操作的应用程序或脚本的管理员，可以使用以下两种方法：

1. Impersonation tokens
2. Sudo

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

{  "message":  "401 Unauthorized"  }

OAuth2 tokens

您可以通过在access_token参数或Authorization标头中传递OAuth2 令牌来对 API 进行身份验证.

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

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

在标头中使用 OAuth2 令牌的示例：

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

阅读有关GitLab 作为 OAuth2 提供程序的更多信息.

Personal/project access tokens

Access tokens can be used to authenticate with the API by passing it in either the private_token parameter or the Private-Token header.

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

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

在标头中使用个人/项目访问令牌的示例：

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

您还可以将个人/项目访问令牌与 OAuth 兼容标头一起使用：

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

Session cookie

登录主 GitLab 应用程序时，将设置_gitlab_session cookie. 如果存在，API 将使用此 cookie 进行身份验证，但是当前不支持使用 API​​生成新的会话 cookie.

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

GitLab CI job token

通过一些 API 端点，您可以使用GitLab CI / CD 作业令牌来对该 API 进行身份验证：

• Get job artifacts
• Pipeline triggers
• Release creation

Impersonation tokens

在 GitLab 9.0 中引入 . 需要管理员权限.

模拟令牌是一种个人访问令牌 ，只能由管理员为特定用户创建. 如果您要构建以特定用户身份通过​​API 进行身份验证的应用程序或脚本，则它们非常适合.

它们是直接使用用户密码或他们的个人访问令牌之一以及使用Sudo功能的替代方法，因为用户（或管理员，对于 Sudo 而言）的密码/令牌可能是未知的，或者可能随时间变化.

有关更多信息，请参考用户 API文档.

模拟令牌的使用与常规个人访问令牌完全一样，并且可以在private_token参数或Private-Token标头中传递.

Disable impersonation

在 GitLab 11.6 中引入 .

默认情况下，模拟是启用的. 禁用模拟：

对于所有安装

1. Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['impersonation_enabled'] = false

2. 保存文件并重新配置 GitLab，以使更改生效.

要重新启用模拟，请删除此配置并重新配置 GitLab.

对于源安装

1. Edit config/gitlab.yml:

   gitlab:
     impersonation_enabled: false

2. 保存文件并重新启动 GitLab，以使更改生效.

要重新启用模拟，请删除此配置并重新启动 GitLab.

Sudo

注意：仅对管理员可用.

如果已通过具有sudo范围的 OAuth 或 Personal Access Token 作为管理员进行身份验证，则所有 API 请求都支持执行 API 调用，就好像您是另一个用户一样.

您需要通过查询字符串或带有您要执行操作的用户的 ID /用户名的标头传递sudo参数. 如果作为标题传递，则标题名称必须为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 request（提供用户名）的请求的示例：

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"

提供 ID 的有效 API 调用和使用 cURL 和 sudo request 的请求的示例：

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"

Status codes

该 API 旨在根据上下文和操作返回不同的状态代码. 这样，如果请求导致错误，则调用者可以洞悉出了什么问题.

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

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

Pagination

我们支持两种分页方法：

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

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

Offset-based pagination

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

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

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

Pagination Link header

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

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

curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/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 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

Other pagination headers

其他分页标题也会发送回.

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

Keyset-based pagination

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

此方法由以下参数控制：

在下面的示例中，我们每页列出 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"

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

HTTP/1.1 200 OK
...
Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
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
...

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

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

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

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

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

Path parameters

如果端点具有路径参数，则文档将在它们前面加上冒号.

例如：

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 编码的路径参数进行解码.

Namespaced path encoding

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

例如， /由/表示：

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

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

File path, branches, and tags name encoding

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

例如， /由/表示：

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

Request Payload

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://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

Array of hashes

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

curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/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://gitlab.example.com/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获取. 有关使用哪个字段的指导，请参阅特定资源的文档.

Data validation and error reporting

使用 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>",  ...  ],  }  }  }

Unknown route

当您尝试访问不存在的 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 建议会将+解释为空格，因此可能需要使用+来代替. 例如，在一个 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

Clients

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

Rate limits

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