REST API 中的资源

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 调用的时区信息。

明确提供带有时区信息的 ISO 8601 时间戳
使用 Time-Zone 标头
使用用户的最后一个已知时区
在没有其他时区信息的情况下默认使用 UTC

请注意，这些规则仅适用于传递给 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 提交。

REST API 中的资源

本文内容