From 4971e1660dd53016ce5b3a0d65ca92d9843656d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=86=8A=E4=BD=B3=E7=89=A7?= Date: Mon, 14 Sep 2020 23:41:24 +0800 Subject: [PATCH] api --- _sidebar.md | 1 + docs/api.md | 414 +++++++++++++++++++++++++++++++++++++ docs/user/profile/token.md | 2 +- 3 files changed, 416 insertions(+), 1 deletion(-) create mode 100644 docs/api.md diff --git a/_sidebar.md b/_sidebar.md index 2450203..84a390c 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -49,6 +49,7 @@ - [管理Issue](docs/user/project/issues/manage) - [里程碑](docs/user/project/milestone) - [Issue排序](docs/user/project/issues/sort) +- [API](/docs/api) - [用户](docs/user) - [举报用户](docs/user/abuse) - [用户账号](docs/user/account) diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..528800a --- /dev/null +++ b/docs/api.md @@ -0,0 +1,414 @@ +# API 文档 + +> 完整的 API 文档参考 Gitlab API docs：[https://docs.gitlab.com/13.2/ee/api/README.html](https://docs.gitlab.com/13.2/ee/api/README.html) + +主要的 GitLab API 是[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API。因此，本文档假定您了解 REST 的概念及知识。 + +## 可用的 API 资源[](#available-api-resources "Permalink") + +有关可用资源及其接口的列表，请参阅[API](https://docs.gitlab.com/13.2/ee/api/api_resources.html) 资源。 + +## 熟悉 GraphQL[](#road-to-graphql "Permalink") + +[GitLab](graphql/index.html)中提供了[GraphQL](https://docs.gitlab.com/13.2/ee/api/graphql/index.html) ，它将允许弃用控制器特定的接口。 + +GraphQL 具有许多优点： + +1. 我们避免维护两个不同的 API +2. API 的调用者只能请求他们需要的东西 +3. 版本已经默认 + +它将与当前的 v4 REST API 共存；如果我们有 v5 API，则它应该是 GraphQL 之上的兼容性层。 + +尽管 GraphQL 存在一些专利和许可问题，但通过 MIT 下的参考实现的重新许可以及 GraphQL 规范使用 OWF 许可证，我们已经满意得解决了这些问题。 + +## 兼容性指引[](#compatibility-guidelines "Permalink") + +HTTP API 使用单个数字进行版本控制，当前版本为 4。此数字与[SemVer](https://semver.org/)描述的主要版本号[相同](https://semver.org/) ，这意味着向后不兼容的更改将需要更改此版本号。但是，次要版本不明确。这可以实现稳定的 API 接口，但也意味着可以将新功能以相同的版本号添加到 API。 + +新功能和错误修复将与新的 GitLab 于每月 22 日发布一起发布，附带的修补程序和安全版本除外。向后不兼容的更改（例如，接口删除，参数删除等）以及整个 API 版本的删除与 GitLab 本身的主要版本一起进行，两个版本之间的所有弃用和更改都应在文档中列出。 对于 v3 和 v4 之间的更改，请阅读[v3 至 v4 文档](https://docs.gitlab.com/13.2/ee/api/v3_to_v4.html)。 + +### 当前版本[](#current-status "Permalink") + +当前仅提供 API 版本 v4，v3 版本已在[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819)中移除。 + +## 基础用法[](#basic-usage "Permalink") + +API 请求应以`api`和 API 版本为前缀，API 版本在[`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/api/api.rb)定义，例如，v4 API 的根位于`/api/v4` 。 + +使用 cURL 的有效 API 请求的示例： + +``` +curl "https://codechina.csdn.net/api/v4/projects" +``` + +该 API 使用 JSON 序列化数据，您无需在 API URL 的末尾指定`.json` 。 + +## 认证[](#authentication "Permalink") + +大多数 API 请求都需要身份验证，或者仅在不提供身份验证时才返回公共数据。对于不需要的情况，将在文档中针对每个接口进行提及，例如， [`/projects/:id`接口](https://docs.gitlab.com/13.2/ee/api/projects.html#get-single-project)。 + +我们建议使用以下方式来进行身份验证： + +1. [Personal access tokens](/docs/user/profile/token-) + +如果身份验证信息无效或被忽略，将返回一条状态码为`401`的错误消息： + +``` +{ "message": "401 Unauthorized" } +``` + +### 用户访问令牌[](#personalproject-access-tokens "Permalink") + +访问令牌可通过 `private_token` 参数或 `Private-Token` 头文件来进行`API`接口的验证。 + +在参数中使用个人访问令牌的示例： + +``` +curl "https://codechina.csdn.net/api/v4/projects?private_token=" +``` + +在头文件使用个人访问令牌的示例： + +``` +curl --header "Private-Token: " "https://codechina.csdn.net/api/v4/projects" +``` + +## 状态码[](#status-codes "Permalink") + +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` | 用户未通过身份验证，有效的[用户令牌](#authentication)是必需的 | +| `403 Forbidden` | 不允许该请求，例如，不允许用户删除项目 | +| `404 Not Found` | 无法访问资源，例如，找不到资源的 ID | +| `405 Method Not Allowed` | 服务器不支持该请求 | +| `409 Conflict` | 已经存在冲突的资源，例如，使用已经存在的名称创建项目 | +| `412` | 表示请求被拒绝 `If-Unmodified-Since`尝试删除资源时提供了`If-Unmodified-Since`标头，则可能会发生这种情况 | +| `422 Unprocessable` | 无法处理该实体 | +| `500 Server Error` | 在处理请求时，服务器端出了问题 | + +## 分页方法[](#pagination "Permalink") + +我们支持两种分页方法： + +* 基于偏移的分页，这是默认方法，并且在所有接口上都可用 +* 基于键集的分页，已添加到选定的接口，但会[逐步推出](https://gitlab.com/groups/gitlab-org/-/epics/2039) + +对于大型集合，出于性能原因，我们建议键集分页（如果有）而不是偏移分页。 + +### 偏移分页[](#offset-based-pagination "Permalink") + +有时，返回的结果将跨越许多页面。列出资源时，可以传递以下参数： + +| 参数 | 说明 | +| --- | --- | +| `page` | 页码（默认： `1` ） | +| `per_page` | 每页要列出的项目数（默认： `20` ，最大： `100` ） | + +在下面的示例中，我们每页列出 50 个名称空间。 + +``` +curl --request PUT --header "PRIVATE-TOKEN: " "https://codechina.csdn.net/api/v4/namespaces?per_page=50" +``` + +#### 分页链接头[](#pagination-link-header "Permalink") + +[链接头](https://www.w3.org/wiki/LinkHeader)随每个响应一起发送回去，它们的`rel`设置为 prev / next / first / last 并包含相关的 URL。请使用这些链接，而不是生成自己的 URL。 + +在下面的 cURL 调用例子中，我们限制输出到每页 3 项（ `per_page=3` ），我们要求的第二页（ `page=2`的） 评论与 ID 问题的`8`属于与 ID 项目`8` ： + +``` +curl --head --header "PRIVATE-TOKEN: " "https://codechina.csdn.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: ; rel="prev", ; rel="next", ; rel="first", ; 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 "Permalink") + +其他分页头信息也会发送回： + +| 头信息 | 说明 | +| --- | --- | +| `X-Total` | 项目总数 | +| `X-Total-Pages` | 总页数 | +| `X-Per-Page` | 每页的项目数 | +| `X-Page` | 当前页面的索引（从 1 开始） | +| `X-Next-Page` | 下一页的索引 | +| `X-Prev-Page` | 前一页的索引 | + +**注意：**由于性能原因，自[GitLab 11.8 起](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931)并**在`api_kaminari_count_with_limit` 功能标志后面** ，如果资源数量大于 10,000，则`X-Total`和`X-Total-Pages`标头以及`rel="last"` `Link`将不存在响应头。 + +### 键集分页[](#keyset-based-pagination "Permalink") + +键集分页可以更有效地检索页面，并且与基于偏移的分页相比，运行时与集合的大小无关。 + +此方法由以下参数控制： + +| 参数 | 说明 | +| --- | --- | +| `pagination` | `keyset` （启用键集分页） | +| `per_page` | 每页要列出的项目数（默认： `20` ，最大： `100` ） | + +在下面的示例中，我们每页列出 50 [个项目](/docs/user/project-) ，并按`id`升序排列。 + +``` +curl --request GET --header "PRIVATE-TOKEN: " "https://codechina.csdn.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" +``` + +响应头包括指向下一页的链接，例如： + +``` +HTTP/1.1 200 OK +... +Links: ; rel="next" +Link: ; rel="next" +Status: 200 OK +... +``` + +**弃用：** `Links`标题将在 GitLab 14.0 中删除，以符合[W3C `Link`规范](https://www.w3.org/wiki/LinkHeader) + +指向下一页的链接包含一个附加过滤器`id_after=42` ，该过滤器不包括我们已经检索到的记录。请注意，过滤器的类型取决于所使用的`order_by`选项，我们可能有多个过滤器。 + +当到达集合的末尾并且没有其他要检索的记录时，将没有`Links`头，并且结果数组为空。 + +我们建议仅使用给定的链接来检索下一页，而不要构建自己的 URL. 除了显示的标题外，我们不公开其他分页标题。 + +仅针对所选资源和订购选项支持基于键集的分页： + +| 资源 | 排序 | +| --- | --- | +| [Projects](/docs/user/project-) | `order_by=id` only | + +## 路径参数[](#path-parameters "Permalink") + +如果接口具有路径参数，则文档将在它们前面加上冒号。 + +例如： + +``` +DELETE /projects/:id/share/:group_id +``` + +`:id`路径参数需要替换为项目 ID，而`:group_id`需要替换为组织的 ID，冒号`:`不应包含在内。 + +因此，对 ID 为`5` ，组 ID 为`17`的项目的 cURL 调用为： + +``` +curl --request DELETE --header "PRIVATE-TOKEN: " "https://codechina.csdn.net/api/v4/projects/5/share/17" +``` + +**注意：**必须遵循要求进行 URL 编码的路径参数。 如果不是，它将与 API 接口不匹配并以 404 进行响应。如果 API 前面有某些内容（例如 Apache），请确保它不会对 URL 编码的路径参数进行解码。 + +## 命名空间路径编码[](#namespaced-path-encoding "Permalink") + +如果使用命名空间的 API 调用，请确保`NAMESPACE/PROJECT_PATH`是 URL 编码的。 + +例如， `/`由`%2F`表示： + +``` +GET /api/v4/projects/diaspora%2Fdiaspora +``` + +**注意：**项目的**路径**不必与**名称**相同，可以在项目的 URL 或项目设置中的**常规>高级>更改路径**下找到项目的**路径** 。 + +## 文件路径、分支、tag 编码[](#file-path-branches-and-tags-name-encoding "Permalink") + +如果文件路径，分支或标记包含`/` ，请确保其经过 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 +``` + +## 请求有效载荷[](#request-payload "Permalink") + +API 请求可以使用作为[查询字符串](https://en.wikipedia.org/wiki/Query_string)或[有效载荷主体](https://tools.ietf.org/html/draft-ietf-httpbis-p3-payload-14#section-3.2)发送的参数。GET 请求通常发送查询字符串，而 PUT / POST 请求通常发送有效内容正文： + +* 请求参数： + + ``` + curl --request POST "https://gitlab/api/v4/projects?name=&description=" + ``` + +* 请求有效载荷（JSON）： + + ``` + curl --request POST --header "Content-Type: application/json" --data '{"name":"", "description":"" \ +-d "import_sources[]=github" \ +-d "import_sources[]=bitbucket" \ +https://codechina.csdn.net/api/v4/some_endpoint +``` + +### `hash`[](#hash "Permalink") + +`override_params`是`hash`类型的参数： + +``` +curl --request POST --header "PRIVATE-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://codechina.csdn.net/api/v4/projects/import +``` + +### hash 键对[](#array-of-hashes "Permalink") + +`variables`是包含哈希键/值对`[{ 'key' => 'UPLOAD_TO_S3', 'value' => 'true' }]` `array`类型的参数： + +``` +curl --globoff --request POST --header "PRIVATE-TOKEN: " \ +"https://codechina.csdn.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: " \ +--header "Content-Type: application/json" \ +--data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ +"https://codechina.csdn.net/api/v4/projects/169/pipeline" +``` + +## `id` vs `iid`[](#id-vs-iid "Permalink") + +Some resources have two similarly-named fields. For example, [issues](issues.html), [merge requests](merge_requests.html), and [project milestones](merge_requests.html). 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 "Permalink") + +使用 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": { "": [ "", "", ... ], "": { "": [ "", "", ... ], } } } +``` + +## 不存在的路由[](#unknown-route "Permalink") + +当您尝试访问不存在的 API URL 时，您将收到 404 Not Found。 + +``` +HTTP/1.1 404 Not Found +Content-Type: application/json +{ + "error": "404 Not Found" +} +``` + +## Encoding `+` in ISO 8601 dates[](#encoding--in-iso-8601-dates "Permalink") + +如果需要在查询参数中包含`+` ，则由于[W3 建议](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html)会将`+`解释为空格，因此可能需要使用`%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 +``` + +## 客户端[](#clients "Permalink") + +大多数流行的编程语言都有许多非官方的 GitLab API 客户端， 访问[GitLab 网站](https://about.gitlab.com/partners/#api-clients)以获取完整列表。 + +## 频率限制[](#rate-limits "Permalink") + +有关速率限制设置的管理员文档，请参阅[速率限制](https://docs.gitlab.com/13.2/ee/security/rate_limits.html)， 要查找 GitLab.com 专门使用的设置，请参阅[GitLab.com 特定的速率限制](https://docs.gitlab.com/13.2/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits) 。 \ No newline at end of file diff --git a/docs/user/profile/token.md b/docs/user/profile/token.md index 86afe9b..14a67da 100644 --- a/docs/user/profile/token.md +++ b/docs/user/profile/token.md @@ -30,7 +30,7 @@ | Scope | 引入 | Description | | --- | --- | --- | -| `read_user` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | 允许访问`/users`下的只读端点。本质上，允许用户 API中的任何`GET`请求 | +| `read_user` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | 允许访问`/users`下的只读接口。本质上，允许用户 API中的任何`GET`请求 | | `api` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | 授予对 API 的完全读写访问权限，包括所有组和项目，容器注册表和程序包注册表 | | `read_api` | [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) | 授予对 API 的读取权限，包括所有组和项目，容器注册表和程序包注册表 | | `read_registry` | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | 如果项目是私有的并且需要授权，则允许读取（拉出） 容器注册表图像 | -- GitLab