API 版本
可用资源可能因不同的 REST API 版本而异。 应使用 X-GitHub-Api-Version
标头指定 API 版本。 有关详细信息,请参阅“API 版本”。
架构
所有 API 访问都通过 HTTPS 进行,并且 从 https://api.github.com
进行访问。 所有数据都以 JSON 格式发送和接收。
$ curl -I https://api.github.com/users/octocat/orgs
> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff
空白字段包含为 null
,而不是被省略。
所有时间戳以 ISO 8601 格式返回 UTC 时间:
YYYY-MM-DDTHH:MM:SSZ
有关时间戳中的时区的详细信息,请参阅本部分。
摘要表示
提取资源列表时,响应包含该资源的属性子集。 这就是资源的“摘要”表示形式。 (对于某些属性,API 要经过大量计算后才可提供。 出于性能考虑,摘要表示排除了这些属性。 要获得这些属性,请获取“详细”表示。)
示例:在获取存储库列表时,会获取每个存储库的摘要表示形式。 在这里,我们提取 octokit 组织拥有的存储库列表:
GET /orgs/octokit/repos
详细表示
提取单个资源时,响应通常包含该资源的所有属性。 这就是资源的“详细”表示形式。 (请注意,授权有时会影响表示形式中包含的详细信息量。)
示例:在获取单个存储库时,会获取该存储库的详细表示形式。 在这里,我们提取 octokit/octokit.rb 存储库:
GET /repos/octokit/octokit.rb
本文档提供每种 API 方法的示例响应。 示例响应说明了该方法返回的所有属性。
身份验证
GitHub 建议创建令牌来对 REST API 进行身份验证。 有关要创建的令牌类型的详细信息,请参阅“对 REST API 进行身份验证”。
你可以通过在请求的 Authorization
标头中发送令牌来对请求进行身份验证:
curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
注意:在大多数情况下,可以使用 Authorization: Bearer
或 Authorization: token
传递令牌。 但是,如果要传递 JSON Web 令牌 (JWT),则必须使用 Authorization: Bearer
。
如果尝试在没有令牌或令牌权限不足的情况下使用 REST API 终结点,你将收到 404 Not Found
或 403 Forbidden
响应。
OAuth2 键/密钥
弃用通知:GitHub 将停止使用查询参数对 API 进行身份验证。 应使用 HTTP 基本身份验证对 API 进行身份验证。 自 2021 年 5 月 5 日起,使用查询参数对 API 进行身份验证将不再有效。 有关详细信息,包括计划限电,请参阅博客文章。
curl -u my_client_id:my_client_secret 'https://api.github.com/user/repos'
使用 client_id
和 client_secret
不会以用户身份进行身份验证,它只会识别 OAuth app 以增加速率限制。 权限仅授予用户,而不授予应用程序,因此只会返回未经验证用户可以看到的数据。 不要向用户泄露 OAuth app 的客户端密码。
有关 OAuth apps 的速率限制的详细信息,请参阅“Rate limits for the REST API”。
失败登录限制
使用无效凭据进行身份验证将返回 401 Unauthorized
:
$ curl -I https://api.github.com --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401
> {
> "message": "Bad credentials",
> "documentation_url": "https://docs.github.com/rest"
> }
在短时间内检测到多个使用无效凭据的请求后,API 将暂时拒绝该用户的所有身份验证尝试(包括使用有效凭据的尝试),并返回 403 Forbidden
:
> HTTP/2 403
> {
> "message": "Maximum number of login attempts exceeded. Please try again later.",
> "documentation_url": "https://docs.github.com/rest"
> }
参数
许多 API 方法采用可选参数。 对于 GET
请求,路径中任何未指定为段的参数都可以作为 HTTP 查询字符串参数进行传递:
curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"
在此示例中,在查询字符串中传递 :state
时,为路径中的 :owner
和 :repo
参数提供“vmg”和“redcarpet”值。
对于 POST
、PATCH
、PUT
和 DELETE
请求,未包含在 URL 中的参数应编码为 JSON,内容类型为“application/json”:
curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' https://api.github.com/authorizations
根终结点
可以向根终结点发出 GET
请求,以获取 REST API 支持的所有终结点类别:
$ curl
-u USERNAME:TOKEN https://api.github.com
GraphQL 全局节点 ID
有关如何通过 REST API 查找 node_id
并在 GraphQL 操作中使用它们的详细信息,请参阅有关“使用全局节点 ID”的指南。
HTTP 谓词
在可能的情况下,GitHub REST API 尽量为每个操作使用适当的 Http 谓词。 请注意,HTTP 谓词区分大小写。
谓词 | 说明 |
---|---|
HEAD | 可以针对任何资源发出以仅获取 HTTP 标头信息。 |
GET | 用于检索资源。 |
POST | 用于创建资源。 |
PATCH | 用于通过部分 JSON 数据更新资源。 例如,问题资源具有 title 和 body 属性。 PATCH 请求可以接受一个或多个属性来更新资源。 |
PUT | 用于替换资源或集合。 对于没有 body 属性的 PUT 请求,请确保将 Content-Length 标头设置为零。 |
DELETE | 用于删除资源。 |
超媒体
所有资源都可以具有一个或多个链接到其他资源的 *_url
属性。 这些属性旨在提供明确的 URL,使适当的 API 客户端不需要自己构建 URL。 强烈建议 API 客户端使用这些属性。 这样做有助于开发者未来更容易升级 API。 所有 URL 都应该是适当的 RFC 6570 URI 模板。
然后,可以使用 uri_template gem 之类的内容来扩展这些模板:
>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"
>> tmpl.expand all: 1
=> "/notifications?all=1"
>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"
必需用户代理
所有 API 请求都必须包含有效的 User-Agent
标头。 没有 User-Agent
标头的请求将被拒绝。 我们要求你使用 GitHub 用户名或应用程序的名称作为 User-Agent
标头值。 这是为了方便我们在发现问题时与您联系 。
下面是一个示例:
User-Agent: Awesome-Octocat-App
默认情况下,curl 发送有效的 User-Agent
标头。 如果通过 curl(或通过备用客户端)提供无效的 User-Agent
标头,则将收到 403 Forbidden
响应:
$ curl -IH 'User-Agent: ' https://api.github.com/meta
> HTTP/1.0 403 Forbidden
> Connection: close
> Content-Type: text/html
> Request forbidden by administrative rules.
> Please make sure your request has a User-Agent header.
> Check for other possible causes.
跨源资源共享
API 支持来自任何源的 AJAX 请求的跨源资源共享 (CORS)。 可以阅读 CORS W3C 建议,或 HTML 5 安全指南中的此简介。
下面是从浏览器点击 http://example.com
发送的请求示例:
$ curl -I https://api.github.com -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
以下是 CORS 预检请求的示例:
$ curl -I https://api.github.com -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400
JSON-P 回调
可以向任何 GET 调用发送 ?callback
参数,以便将结果包装在 JSON 函数中。 当浏览器希望绕开跨域问题将 GitHub 内容嵌入网页时,通常使用此方法。 响应包括与常规 API 相同的数据输出,加上相关的 HTTP 标头信息。
$ curl https://api.github.com?callback=foo
> /**/foo({
> "meta": {
> "status": 200,
> "x-ratelimit-limit": "5000",
> "x-ratelimit-remaining": "4966",
> "x-ratelimit-reset": "1372700873",
> "Link": [ // pagination headers and other links
> ["https://api.github.com?page=2", {"rel": "next"}]
> ]
> },
> "data": {
> // the data
> }
> })
您可以编写一个 JavaScript 处理程序来处理回调。 以下是一个最小的处理程序示例,您可以尝试编写:
<html>
<head>
<script type="text/javascript">
function foo(response) {
var meta = response.meta;
var data = response.data;
console.log(meta);
console.log(data);
}
var script = document.createElement('script');
script.src = 'https://api.github.com?callback=foo';
document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>
<body>
<p>Open up your browser's console.</p>
</body>
</html>
所有标头都具有与 HTTP 标头相同的字符串值,但有一个值得注意的例外:链接。 链接标头已预先解析,并以 [url, options]
元组的数组形式出现。
链接如下所示:
Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"
... 在回调输出中将如下所示:
{
"Link": [
[
"url1",
{
"rel": "next"
}
],
[
"url2",
{
"rel": "foo",
"bar": "baz"
}
]
]
}
时区
某些创建新数据的请求(例如创建新的提交)允许您在指定或生成时间戳时提供时区信息。 我们按照优先顺序应用以下规则来确定这些 API 调用的时区信息。
请注意,这些规则仅适用于传递给 API 的数据,而不适用于 API 返回的数据。 如“架构”中所述,API 返回的时间戳采用 UTC 时间、ISO 8601 格式。
明确提供带有时区信息的 ISO 8601 时间戳
对于允许指定时间戳的 API 调用,我们使用这种明确的时间戳。 其中一个示例是用于管理提交的 API。 有关详细信息,请参阅“Git 数据库”。
这些时间戳类似于 2014-02-27T15:05:06+01:00
。 如需了解如何指定这些时间戳,另请参阅此示例。
使用 Time-Zone
标头
可以提供一个 Time-Zone
标头,该标头根据 Olson 数据库中的名称列表定义时区。
curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github-linguist/linguist/contents/new_file.md
这意味着当您在这个标题定义的时区做出 API 调用时,我们会生成一个时间戳。 例如,用于管理内容的 API 会为每个添加或更改生成 git 提交,并使用当前时间作为时间戳。 有关详细信息,请参阅“存储库”。 此标头将确定用于生成当前时间戳的时区。
使用用户的最后一个已知时区
如果未指定 Time-Zone
标头,并且你对 API 进行经过身份验证的调用,则我们对经过身份验证的用户使用最后一个已知时区。 最新一个已知的时区在您浏览 GitHub 网站时都会更新。
在没有其他时区信息的情况下默认使用 UTC
如果上述步骤未产生任何信息,我们将使用 UTC 作为时区来创建 git 提交。