284.md

# API Docs

> 原文：[https://docs.gitlab.com/ee/api/README.html](https://docs.gitlab.com/ee/api/README.html)

*   [Available API resources](#available-api-resources)
*   [SCIM](#scim-silver-only)
*   [Road to GraphQL](#road-to-graphql)
*   [Compatibility guidelines](#compatibility-guidelines)
    *   [Current status](#current-status)
*   [Basic usage](#basic-usage)
*   [Authentication](#authentication)
    *   [OAuth2 tokens](#oauth2-tokens)
    *   [Personal/project access tokens](#personalproject-access-tokens)
    *   [Session cookie](#session-cookie)
    *   [GitLab CI job token](#gitlab-ci-job-token)
    *   [Impersonation tokens](#impersonation-tokens)
        *   [Disable impersonation](#disable-impersonation)
    *   [Sudo](#sudo)
*   [Status codes](#status-codes)
*   [Pagination](#pagination)
    *   [Offset-based pagination](#offset-based-pagination)
        *   [Pagination Link header](#pagination-link-header)
        *   [Other pagination headers](#other-pagination-headers)
    *   [Keyset-based pagination](#keyset-based-pagination)
*   [Path parameters](#path-parameters)
*   [Namespaced path encoding](#namespaced-path-encoding)
*   [File path, branches, and tags name encoding](#file-path-branches-and-tags-name-encoding)
*   [Request Payload](#request-payload)
*   [Encoding API parameters of `array` and `hash` types](#encoding-api-parameters-of-array-and-hash-types)
    *   [`array`](#array)
    *   [`hash`](#hash)
    *   [Array of hashes](#array-of-hashes)
*   [`id` vs `iid`](#id-vs-iid)
*   [Data validation and error reporting](#data-validation-and-error-reporting)
*   [Unknown route](#unknown-route)
*   [Encoding `+` in ISO 8601 dates](#encoding--in-iso-8601-dates)
*   [Clients](#clients)
*   [Rate limits](#rate-limits)

# API Docs[](#api-docs "Permalink")

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

主要的 GitLab API 是[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. 因此，本节中的文档假定您具有 REST 概念的知识.

## Available API resources[](#available-api-resources "Permalink")

有关可用资源及其端点的列表，请参阅[API 资源](api_resources.html) .

## SCIM[](#scim-silver-only "Permalink")

[GitLab.com Silver 和更高版本](https://about.gitlab.com/pricing/)提供了[SCIM API](scim.html) ， [该](https://tools.ietf.org/html/rfc7644) [API](scim.html)实现[RFC7644 协议](https://tools.ietf.org/html/rfc7644)并提供`/Users`端点. 基本网址为： `/api/scim/v2/groups/:group_path/Users/` .

## Road to GraphQL[](#road-to-graphql "Permalink")

[GitLab](graphql/index.html)中提供了[GraphQL](graphql/index.html) ，它将允许弃用控制器特定的端点.

GraphQL 具有许多优点：

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

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

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

## Compatibility guidelines[](#compatibility-guidelines "Permalink")

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

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

### Current status[](#current-status "Permalink")

当前仅提供 API 版本 v4\. v3 版本已在[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819)中删除.

## Basic usage[](#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://gitlab.example.com/api/v4/projects" 
```

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

## Authentication[](#authentication "Permalink")

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

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

1.  [OAuth2 tokens](#oauth2-tokens)
2.  [Personal access tokens](../user/profile/personal_access_tokens.html)
3.  [Project access tokens](../user/project/settings/project_access_tokens.html)
4.  [Session cookie](#session-cookie)
5.  [GitLab CI/CD job token](#gitlab-ci-job-token) **（仅特定端点）**

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

1.  [Impersonation tokens](#impersonation-tokens)
2.  [Sudo](#sudo)

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

```
{  "message":  "401 Unauthorized"  } 
```

### OAuth2 tokens[](#oauth2-tokens "Permalink")

您可以通过在`access_token`参数或`Authorization`标头中传递[OAuth2 令牌](oauth2.html)来对 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 提供程序的](oauth2.html)更多信息.

### Personal/project access tokens[](#personalproject-access-tokens "Permalink")

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[](#session-cookie "Permalink")

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

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

### GitLab CI job token[](#gitlab-ci-job-token "Permalink")

通过一些 API 端点，您可以使用[GitLab CI / CD 作业令牌](../user/project/new_ci_build_permissions_model.html#job-token)来对该 API 进行身份验证：

*   [Get job artifacts](jobs.html#get-job-artifacts)
*   [Pipeline triggers](pipeline_triggers.html)
*   [Release creation](releases/index.html#create-a-release)

### Impersonation tokens[](#impersonation-tokens "Permalink")

在 GitLab 9.0 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9099) . 需要管理员权限.

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

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

有关更多信息，请参考[用户 API](users.html#create-an-impersonation-token)文档.

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

#### Disable impersonation[](#disable-impersonation "Permalink")

在 GitLab 11.6 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/40385) .

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

**对于所有安装**

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

    ```
    gitlab_rails['impersonation_enabled'] = false 
    ```

2.  保存文件并[重新配置](../administration/restart_gitlab.html#omnibus-gitlab-reconfigure) GitLab，以使更改生效.

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

**对于源安装**

1.  Edit `config/gitlab.yml`:

    ```
    gitlab:
      impersonation_enabled: false 
    ```

2.  保存文件并[重新启动](../administration/restart_gitlab.html#installations-from-source) GitLab，以使更改生效.

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

### Sudo[](#sudo "Permalink")

**注意：**仅对[管理员](../user/permissions.html)可用.

如果已通过具有`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[](#status-codes "Permalink")

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

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

| 请求类型 | Description |
| --- | --- |
| `GET` | 访问一个或多个资源，并将结果作为 JSON 返回. |
| `POST` | 如果成功创建资源，则返回`201 Created` ，然后将新创建的资源作为 JSON 返回. |
| `GET` / `PUT` | 如果成功访问或修改了资源，则返回`200 OK` . （修改后的）结果作为 JSON 返回. |
| `DELETE` | 如果资源已成功删除，则返回`204 No Content` . |

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

| 返回值 | Description |
| --- | --- |
| `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` | The request is not supported. |
| `409 Conflict` | 已经存在冲突的资源，例如，使用已经存在的名称创建项目. |
| `412` | 表示请求被拒绝. `If-Unmodified-Since`尝试删除资源时提供了`If-Unmodified-Since`标头，则可能会发生这种情况. |
| `422 Unprocessable` | 无法处理该实体. |
| `500 Server Error` | 在处理请求时，服务器端出了点问题. |

## Pagination[](#pagination "Permalink")

我们支持两种分页方法：

*   基于偏移的分页. 这是默认方法，并且在所有端点上都可用.
*   基于键集的分页. 已添加到选定的端点，但会[逐步推出](https://gitlab.com/groups/gitlab-org/-/epics/2039) .

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

### Offset-based pagination[](#offset-based-pagination "Permalink")

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

| Parameter | Description |
| --- | --- |
| `page` | 页码（默认： `1` ） |
| `per_page` | 每页要列出的项目数（默认： `20` ，最大： `100` ） |

在下面的示例中，我们每页列出 50 个[名称空间](namespaces.html) .

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

#### Pagination Link header[](#pagination-link-header "Permalink")

[链接头](https://www.w3.org/wiki/LinkHeader)随每个响应一起发送回去. 它们的`rel`设置为 prev / next / first / last 并包含相关的 URL. 请使用这些链接，而不是生成自己的 URL.

在下面的卷曲的例子，我们限制输出到每页 3 项（ `per_page=3` ），我们要求的第二页（ `page=2`的） [评论](notes.html)与 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[](#other-pagination-headers "Permalink")

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

| Header | Description |
| --- | --- |
| `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` [功能标志](../development/feature_flags/index.html)后面** ，如果资源数量大于 10,000，则`X-Total`和`X-Total-Pages`标头以及`rel="last"` `Link`将不存在响应头.

### Keyset-based pagination[](#keyset-based-pagination "Permalink")

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

此方法由以下参数控制：

| Parameter | Description |
| --- | --- |
| `pagination` | `keyset` （启用键集分页） |
| `per_page` | 每页要列出的项目数（默认： `20` ，最大： `100` ） |

在下面的示例中，我们每页列出 50 [个项目](projects.html) ，并按`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`规范](https://www.w3.org/wiki/LinkHeader)

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

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

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

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

| Resource | Order |
| --- | --- |
| [Projects](projects.html) | `order_by=id` only |

## Path parameters[](#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://gitlab.example.com/api/v4/projects/5/share/17" 
```

**注意：**必须遵循要求进行 URL 编码的路径参数. 如果不是，它将与 API 端点不匹配并以 404 进行响应.如果 API 前面有某些内容（例如 Apache），请确保它不会对 URL 编码的路径参数进行解码.

## Namespaced path encoding[](#namespaced-path-encoding "Permalink")

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

例如， `/`由`/`表示：

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

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

## File path, branches, and tags name encoding[](#file-path-branches-and-tags-name-encoding "Permalink")

如果文件路径，分支或标记包含`/` ，请确保其经过 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[](#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://gitlab.example.com/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://gitlab.example.com/api/v4/projects/import 
```

### Array of hashes[](#array-of-hashes "Permalink")

`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`[](#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[](#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[](#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)会将`+`解释为空格，因此可能需要使用`+`来代替. 例如，在一个 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[](#clients "Permalink")

大多数流行的编程语言都有许多非官方的 GitLab API 客户端. 访问[GitLab 网站](https://about.gitlab.com/partners/#api-clients)以获取完整列表.

## Rate limits[](#rate-limits "Permalink")

有关速率限制设置的管理员文档，请参阅[速率限制](../security/rate_limits.html) . 要查找 GitLab.com 专门使用的设置，请参阅[GitLab.com 特定的速率限制](../user/gitlab_com/index.html#gitlabcom-specific-rate-limits) .