提交 4971e166 编写于 作者: Lab机器人's avatar Lab机器人

api

上级 d80fe03d
...@@ -49,6 +49,7 @@ ...@@ -49,6 +49,7 @@
- [管理Issue](docs/user/project/issues/manage) - [管理Issue](docs/user/project/issues/manage)
- [里程碑](docs/user/project/milestone) - [里程碑](docs/user/project/milestone)
- [Issue排序](docs/user/project/issues/sort) - [Issue排序](docs/user/project/issues/sort)
- [API](/docs/api)
- [用户](docs/user) - [用户](docs/user)
- [举报用户](docs/user/abuse) - [举报用户](docs/user/abuse)
- [用户账号](docs/user/account) - [用户账号](docs/user/account)
......
# 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
...@@ -30,7 +30,7 @@ ...@@ -30,7 +30,7 @@
| Scope | 引入 | Description | | 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 的完全读写访问权限,包括所有组和项目,容器注册表和程序包注册表 | | `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_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) | 如果项目是私有的并且需要授权,则允许读取(拉出) 容器注册表图像 | | `read_registry` | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | 如果项目是私有的并且需要授权,则允许读取(拉出) 容器注册表图像 |
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册