Help us learn about your current experience with the documentation. Take the survey.

记录 REST API 资源

REST API 资源在 Markdown 中记录在 /doc/api 下。每个资源都有自己的 Markdown 文件，该文件从 api_resources.md 链接。

修改 Markdown 或 API 代码时，还需通过运行 bin/rake gitlab:openapi:generate 来更新相应的 OpenAPI 定义。要检查 OpenAPI 定义是否需要更新，可以运行 bin/rake gitlab:openapi:check_docs。openapi-doc-check CI/CD 作业也会检查修改 API 代码或文档的提交。

在资源的 Markdown 文档中（即 API 端点）：

每个方法都必须包含 REST API 请求。请求应包含 HTTP 方法（如 GET、PUT、DELETE），后跟请求路径。路径必须始终以 / 开头。例如：
```
GET /api/v4/projects/:id/repository/branches
```
每个方法都必须有详细的属性描述。
每个方法都必须有一个 cURL 示例。
每个方法都必须有详细的响应体描述。
每个方法都必须有一个响应体示例（JSON 格式）。
如果某个属性仅适用于更高级别的订阅套餐，请在描述中添加相应的套餐级别。如果属性适用于 Premium，还需注明它也适用于 Ultimate。
如果某个属性仅在特定产品中可用，请在描述中添加这些产品。如果属性的描述同时包含产品和套餐级别，请将它们组合起来。例如：仅限 GitLab 自托管版、Premium 和 Ultimate。

添加新的 API 文档页面后，在全局导航中添加条目。示例。

API 主题模板

使用以下模板帮助您开始。确保在表格中首先列出任何必需的属性。

## API 名称

{{< history >}}

- 历史记录。

{{< /history >}}

对端点功能的一两句话描述。

### 方法标题

{{< history >}}

- 历史记录。

{{< /history >}}

方法的描述。

```plaintext
METHOD /api/v4/endpoint
```

支持的属性：

| 属性                | 类型     | 必需 | 描述           |
|---------------------|----------|------|----------------|
| `attribute`         | datatype | 是   | 详细描述。     |
| `attribute`         | datatype | 否   | 详细描述。     |
| `attribute`         | datatype | 否   | 详细描述。     |
| `attribute`         | datatype | 否   | 详细描述。     |

如果成功，返回 [`<状态码>`](rest/troubleshooting.md#status-codes) 和以下响应属性：

| 属性                | 类型     | 描述           |
|---------------------|----------|----------------|
| `attribute`         | datatype | 详细描述。     |
| `attribute`         | datatype | 详细描述。     |

示例请求：

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/endpoint?parameters"
```

示例响应：

```json
[
  {
  }
]
```

历史记录

添加历史记录来描述新的或更新的 API 调用。

要为单个属性添加历史记录，请将其包含在该部分的历史记录中。例如：

### 编辑小部件

{{< history >}}

 - `widget_message` [在 GitLab 14.3 中引入](https://link-to-issue)。

{{< /history >}}

如果 API 或属性在功能标志后部署，请在历史记录中包含功能标志信息。

废弃

要记录 API 端点的废弃，请遵循废弃页面或主题的步骤。

要废弃一个属性：

添加历史记录。

{{< history >}}

- `widget_name` [在 GitLab 14.7 中废弃](https://link-to-issue)。

{{< /history >}}

在描述中添加内联废弃文本。

| 属性        | 类型   | 必需 | 描述 |
|-------------|--------|------|------|
| `widget_name` | string | 否   | [在 GitLab 14.7 中废弃](https://link-to-issue)。改用 `widget_id`。小部件的名称。 |

要广泛宣布废弃，请更新 REST API 废弃页面。

方法描述

使用以下表头描述方法。属性应始终使用反引号（`）放在代码块中。

首先按必需属性排序，然后按字母顺序排序。

| 属性                    | 类型          | 必需 | 描述                                         |
|-------------------------|---------------|------|----------------------------------------------|
| `title`                 | string        | 是   | 问题的标题。                                 |
| `assignee_ids`          | integer array | 否   | 分配问题的用户 ID。仅限 Ultimate。           |
| `confidential`          | boolean       | 否   | 将问题设置为保密。默认为 `false`。           |

渲染后的示例：

属性	类型	必需	描述
`title`	string	是	问题的标题。
`assignee_ids`	integer array	否	分配问题的用户 ID。Premium 和 Ultimate 仅限。
`confidential`	boolean	否	将问题设置为保密。默认为 `false`。

有关编写属性描述的信息，请参阅 GraphQL API 描述风格指南。

条件必需属性

如果有属性，其中任何一个或两个都是进行 API 请求所必需的：

在"必需"列中添加"条件"。

在描述中清楚地描述相关属性。您可以使用以下模板：

至少必须包含 `attribute1` 或 `attribute2` 中的一个。如果需要，两者都可以使用。

例如：

属性	类型	必需	描述
`include_saml_users`	boolean	条件	包含具有 SAML 身份的用户。至少必须包含 `include_saml_users` 或 `include_service_accounts` 中的一个，且必须为 `true`。如果需要，两者都可以使用。
`include_service_accounts`	boolean	条件	包含服务账户用户。至少必须包含 `include_saml_users` 或 `include_service_accounts` 中的一个，且必须为 `true`。如果需要，两者都可以使用。

响应体描述

用以下句子开始描述，将"状态代码"替换为相关的HTTP 状态代码，例如：

如果成功，返回 [`200 OK`](../../api/rest/troubleshooting.md#status-codes) 和以下响应属性：

使用以下表头描述响应体。属性应始终使用反引号（`）放在代码块中。

如果属性是复杂类型，如另一个对象，则用点（.）表示子属性，如 project.name 或数组中的 projects[].name。

按字母顺序对表格进行排序。

| 属性                    | 类型          | 描述                               |
|-------------------------|---------------|------------------------------------|
| `assignee_ids`          | integer array | 分配问题的用户 ID。Premium 和 Ultimate 仅限。 |
| `confidential`          | boolean       | 问题是否为保密。                   |
| `title`                 | string        | 问题的标题。                       |

渲染后的示例：

属性	类型	描述
`assignee_ids`	integer array	分配问题的用户 ID。Premium 和 Ultimate 仅限。
`confidential`	boolean	问题是否为保密。
`title`	string	问题的标题。

有关编写属性描述的信息，请参阅 GraphQL API 描述风格指南。

cURL 命令

使用 https://gitlab.example.com/api/v4/ 作为端点。
在需要的地方使用此个人访问令牌：<your_access_token>。
始终将请求放在第一位。GET 是默认值，因此无需包含它。
为提高可读性，使用长选项名称（--header 而不是 -H）。（已在 scripts/lint-doc.sh 中测试。）
使用 --url 参数声明 URL，并将 URL 包含在双引号（"）中。
优先使用使用个人访问令牌的示例，不要传递用户名和密码数据。
为提高可读性，使用 \ 字符和缩进来将长单行命令拆分为多行。

方法	描述
`--header "PRIVATE-TOKEN: <your_access_token>"`	需要身份验证时直接使用此方法。
`--request POST`	创建新对象时使用此方法。
`--request PUT`	更新现有对象时使用此方法。
`--request DELETE`	删除现有对象时使用此方法。

cURL 示例

以下部分包含一组可用于 API 文档的 cURL 示例。

不要使用真实用户的信息、URL 或令牌。有关文档，请参阅我们关于假用户信息、假 URL 和假令牌的相关风格指南部分。

简单的 cURL 命令

获取组的详细信息：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/gitlab-org"

在 URL 中传递参数的 cURL 示例

在经过身份验证的用户命名空间下创建新项目：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects?name=foo"

使用 cURL 的 `--data` 发送数据

不要使用 --request POST 并将参数附加到 URI，而是可以使用 cURL 的 --data 选项。下面的示例将在经过身份验证的用户命名空间下创建一个新项目 foo。

curl --data "name=foo" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

使用 JSON 内容发送数据

此示例创建一个新组。请注意单引号（'）和双引号（"）的使用。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"path": "my-group", "name": "My group"}' \
  --url "https://gitlab.example.com/api/v4/groups"

为提高可读性，您还可以使用以下格式设置 --data：

curl --request POST \
  --url "https://gitlab.example.com/api/v4/groups" \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data '{
    "path": "my-group",
    "name": "My group"
}'

使用 form-data 发送数据

不要使用 JSON 或 URL 编码数据，可以使用 multipart/form-data 来正确处理数据编码：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "title=ssh-key" \
  --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." \
  --url "https://gitlab.example.com/api/v4/users/25/keys"

上面的示例将一个名为 ssh-key 的 SSH 公钥添加到 ID 为 25 的用户账户。此操作需要管理员权限。

转义特殊字符

空格或斜杠（/）有时会导致错误，因此应尽可能转义它们。在下面的示例中，我们创建了一个标题中包含空格的新问题。请注意如何使用 %20 ASCII 代码转义空格。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20GitLab"

对斜杠（/）使用 %2F。

向 API 调用传递数组

GitLab API 有时接受字符串或整数数组。例如，在请求项目用户列表时排除特定用户，您可以这样做：

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>"
  --data "skip_users[]=<user_id>" \
  --data "skip_users[]=<user_id>" \
  --url "https://gitlab.example.com/api/v4/projects/<project_id>/users"