api

_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)

docs/api.md

+# 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=<your_access_token>" 
+```
+
+在头文件使用个人访问令牌的示例：
+
+```
+curl --header "Private-Token: <your_access_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: <your_access_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: <your_access_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: <https://codechina.csdn.net/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 "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: <your_access_token>" "https://codechina.csdn.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" 
+```
+
+响应头包括指向下一页的链接，例如：
+
+```
+HTTP/1.1 200 OK
+...
+Links: <https://codechina.csdn.net/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
+Link: <https://codechina.csdn.net/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`规范](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: <your_access_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=<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[](#encoding-api-parameters-of-array-and-hash-types "Permalink")
+
+我们可以使用`array`和`hash`类型参数调用 API，如下所示：
+
+### `array`[](#array "Permalink")
+
+`import_sources`是`array`类型的参数：
+
+```
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+-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: <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://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: <your_access_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: <your_access_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":  {  "<property-name>":  [  "<error-message>",  "<error-message>",  ...  ],  "<embed-entity>":  {  "<property-name>":  [  "<error-message>",  "<error-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

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) | 如果项目是私有的并且需要授权，则允许读取（拉出） 容器注册表图像 |