跳到内容

GitLab API

通过一个简单而强大的API自动化GitLab。所有定义都可以在下面找到/lib/api．

资源

各种API资源的文档可以分别在以下位置找到:

GraphQL之路

接下来，我们将开始讲GraphQL并且不建议使用特定于控制器的端点。GraphQL有很多优点:

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

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

尽管GraphQL存在一些专利和许可方面的问题，但这些问题已经通过在MIT下对参考实现的重新授权，以及对GraphQL规范使用OWF许可，得到了满意的解决。

兼容性指南

HTTP API使用一个数字进行版本控制，当前的数字是4。此数字与描述的主要版本号相同SemVer．这意味着向后不兼容的更改将要求更改此版本号。但是，次要版本并不明确。这允许一个稳定的API端点，但也意味着可以以相同的版本号向API添加新特性。

新功能和错误修复与新的GitLab一起发布，除了附带的补丁和安全版本外，每个月22日发布。向后不兼容的更改(例如端点删除，参数删除等)，以及整个API版本的删除都是与GitLab本身的主要点版本一起完成的。两个版本之间的所有弃用和更改都应该在文档中列出。对于v3和v4之间的变化;请细阅V3到v4文档

当前的状态

目前有v3和v4两个API版本可用。V3已弃用，将很快被移除。计划删除GitLab 11.0．

基本用法

API请求的前缀应该是api及API版本。API版本定义在lib / api.rb．例如，v4 API的根在/ api / v4．

使用cURL的有效API请求示例:

旋度“https://gitlab.example.com/api/v4/projects”

API使用JSON序列化数据。你不需要详细说明. json在API URL的末尾。

身份验证

大多数API请求都需要身份验证，或者只在不提供身份验证时才返回公共数据。对于不需要的情况，将在文档中针对每个端点提到这一点。例如，/ /项目:id端点．

使用GitLab API进行身份验证有三种方式:

  1. OAuth2令牌
  2. 个人访问令牌
  3. 会话cookie

对于想要作为特定用户使用API进行身份验证的管理员，或者想要构建这样做的应用程序或脚本的管理员，有两个选项:

  1. 模拟令牌
  2. Sudo

如果身份验证信息无效或省略，将返回带有状态码的错误消息401：

｛“消息”：“401未授权”｝

OAuth2令牌

你可以使用OAuth2令牌属性中传递API来进行身份验证access_token参数或授权头。

在参数中使用OAuth2令牌的示例:

curl https://gitlab.example.com/api/v4/projects?access_token＝OAUTH-TOKEN

在报头中使用OAuth2令牌的例子:

旋度——头“授权:持名OAUTH-TOKEN”https://gitlab.example.com/api/v4/projects

阅读更多GitLab作为OAuth2提供者．

个人访问令牌

你可以使用个人访问令牌属性中传递API来进行身份验证private_token参数或Private-Token头。

在参数中使用个人访问令牌的示例:

curl https://gitlab.example.com/api/v4/projects?private_token＝9 koxpg98eahejpvbs5tk

在头文件中使用个人访问令牌的例子:

旋度——头“Private-Token: 9 koxpg98eahejpvbs5tk”https://gitlab.example.com/api/v4/projects

阅读更多个人访问令牌．

会话cookie

当登录到主GitLab应用程序时，一个_gitlab_session琦琦准备好了。如果该cookie存在，API将使用该cookie进行身份验证，但目前不支持使用API生成新的会话cookie。

这种身份验证方法的主要用户是GitLab本身的web前端，它可以使用API作为经过身份验证的用户来获得他们的项目列表，而不需要显式地传递访问令牌。

模拟令牌

介绍了在GitLab 9.0中。需要管理权限。

模拟令牌是一种个人访问令牌只能由管理员为特定用户创建。如果您希望构建作为特定用户使用API进行身份验证的应用程序或脚本，那么它们非常适合。

它们是直接使用用户密码或其个人访问令牌之一，以及使用Sudo特性，因为用户(或者Sudo中的管理员)的密码/令牌可能不知道，或者可能随着时间的推移而改变。

有关更多信息，请参阅用户API文档。

模拟令牌的使用与常规的个人访问令牌完全相同，并且可以在private_token参数或Private-Token头。

Sudo

需要管理权限。

所有API请求都支持执行API调用，就像您是另一个用户一样，前提是您通过具有OAuth或个人访问令牌的管理员身份验证sudo范围。

你需要通过sudo参数可以通过查询字符串，也可以通过带有你想要执行操作的用户ID/用户名的头文件。如果作为头传递，头名必须为Sudo．

如果提供了非管理访问令牌，则将返回带有状态码的错误消息403：

｛“消息”："403禁止-必须是管理员使用sudo"｝

的访问令牌sudo范围时，将返回带有状态码的错误消息403：

｛“错误”：“insufficient_scope”，“error_description”：请求需要比访问令牌提供的权限更高的权限。，“范围”：“sudo”｝

如果找不到sudo用户ID或用户名，将返回一条带有状态码的错误消息404：

｛“消息”："404用户ID或用户名'123'未找到"｝

一个有效的API调用和请求的例子，使用cURL和sudo请求，提供一个用户名:

GET /项目?private_token＝9 koxpg98eahejpvbs5tk&sudo=username
旋度——头“Private-Token: 9 koxpg98eahejpvbs5tk”——头“Sudo:用户名”“https://gitlab.example.com/api/v4/projects”

一个有效的API调用和请求的例子，使用cURL和sudo请求，提供一个ID:

GET /项目?private_token＝9 koxpg98eahejpvbs5tk&sudo=23
旋度——头“Private-Token: 9 koxpg98eahejpvbs5tk”——头“Sudo: 23日”“https://gitlab.example.com/api/v4/projects”

状态码

该API被设计为根据上下文和操作返回不同的状态代码。这样，如果请求导致错误，调用者就能够了解出错的地方。

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

请求类型 描述
得到 访问一个或多个资源并以JSON形式返回结果。
帖子 返回201年创建如果资源成功创建，并以JSON的形式返回新创建的资源。
得到/把 返回200好了访问或修改资源成功。(修改后的)结果作为JSON返回。
删除 返回204无内容删除资源成功。

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

返回值 描述
200好了 的得到，把或删除如果请求成功，资源本身将以JSON格式返回。
204无内容 服务器已经成功地完成了请求，并且在响应有效负载主体中没有要发送的其他内容。
201年创建 的帖子请求成功，资源以JSON形式返回。
304未修改 指示自上次请求以来未修改过资源。
400错误请求 缺少API请求的必需属性，例如，没有给出问题的标题。
401年未经授权 用户未经过身份验证，无效用户令牌是必要的。
403年被禁止的 不允许该请求，例如，不允许用户删除一个项目。
404未找到 无法访问资源，例如，无法找到资源的ID。
405方法不允许 请求不支持。
409年冲突 冲突资源已经存在，例如，创建一个名称已经存在的项目。
412 表示请求被拒绝。可能发生，如果If-Unmodified-Since当试图删除一个资源时，将提供头，该资源在两者之间被修改。
422年Unprocessable 无法处理该实体。
服务器错误 在处理请求时，服务器端出现了错误。

分页

有时返回的结果会跨越许多页。在列出资源时，您可以传递以下参数:

参数 描述
页面 页码(默认:1)
per_page 每页要列出的项目数量(默认:20.马克斯:One hundred.)

在下面的例子中，我们列出了50个名称空间每个页面。

旋度——请求把——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”“https://gitlab.example.com/api/v4/namespaces?per_page=50

链接头

链接标题与每个响应一起返回。他们有rel设置为前/下/第一个/最后一个，并包含相关的URL。请使用这些链接，而不是生成自己的url。

在下面的cURL示例中，我们将每页输出限制为3个条目(per_page = 3)，我们请求第二页(页面= 2)评论身份证的问题8有ID的项目属于哪个8：

旋度——头——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page＝3和页面＝2

回答将是:

Http /1.1 200 okcache - control: no - cache内容长度:1103内容类型:application / json日期:2016年1月18日星期一09:43:18 GMT链接:< https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3 >;rel = "上一页",< https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3 >;rel = "下一个",< https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3 >;rel =“第一”,< https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3 >;rel = "最后一次"状态:200 OK不同:起源X-Next-Page: 3X-Page: 2X-Per-Page: 3X-Prev-Page: 1ad4ee X-Request-Id: 732 - 9870 - 4866 - a199 a9db0cde3c86X-Runtime: 0.108688乘以总:8X-Total-Pages: 3

其他分页标头

附加的分页标头也被发回。

头 描述
乘以总 项目总数
X-Total-Pages 总页数
X-Per-Page 每页的条目数
X-Page 当前页面的索引(从1开始)
X-Next-Page 下一页的索引
X-Prev-Page 上一页的索引

命名空间路径编码

如果使用名称空间API调用，请确保命名空间/ PROJECT_NAMEurl编码。

例如,/表示为% 2 f：

GET / api / v4 /项目/侨民fdiaspora % 2

分支和标签名称编码

如果分支或标记包含/，确保分支/标记名称是url编码的。

例如,/表示为% 2 f：

GET / api / v4 /项目/ 1 /分支/我的% 2 fbranch /提交

idvsiid

当你使用API时，你可能会注意到API实体中有两个类似的字段:id而且iid．它们之间的主要区别是范围。

例如，一个问题可能存在id: 46而且iid: 5．

参数 描述
id 在所有问题上是唯一的，并用于任何API调用
iid 仅在单个项目的范围内是唯一的。当您使用Web UI浏览问题或合并请求时，您将看到iid

这意味着如果你想通过API得到一个问题，你应该使用id：

GET /项目/ 42 /问题/:id

另一方面，如果你想创建一个链接到网页，你应该使用iid：

GET /项目/ 42 /问题/:iid

数据验证和错误报告

在使用API时，您可能会遇到验证错误，在这种情况下，API将用HTTP回答400的地位。

这种错误出现在两种情况下:

  • 缺少API请求的必需属性，例如，没有给出问题的标题
  • 一个属性没有通过验证，例如，用户简介太长

当一个属性缺失时，你会得到类似这样的东西:

HTTP/1.1 400错误请求内容类型:application / json｛"message":"400(错误请求)\"title\"未给出"｝

当发生验证错误时，错误消息将有所不同。它们将保存验证错误的所有细节:

HTTP/1.1 400错误请求内容类型:application / json｛"信息":{“生物”:(“太长(最大255个字符)”］｝｝

这使得错误消息更具机器可读性。格式说明如下:

｛“消息”：｛“<属性名>”：［“<错误消息>”，“<错误消息>”，…),“< embed-entity >”：｛“<属性名>”：［“<错误消息>”，“<错误消息>”，…),｝｝｝

未知的路

当您尝试访问一个不存在的API URL时，您将收到404 not Found。

HTTP/1.1 404未找到内容类型:application / json｛"error": "404 Not Found"｝

编码+ISO 8601日期

如果你需要一个+在查询参数中，可能需要使用% 2 b相反，由于W3推荐这就导致了+被解释为一个空间。例如，在ISO 8601日期中，您可能希望使用山地标准时间传递时间，例如:

2017 - 10 - 17 t23:11:13.000 + 05:30

查询参数的正确编码是:

2017 - 10 - 17 t23:11:13.000 b05:30 % 2

客户

大多数流行的编程语言都有许多非官方的GitLab API客户端。参观GitLab网站一个完整的列表。

Baidu
map