REST API 入门

默认情况下，curl 会发送有效的 User-Agent 标头。但是，GitHub 建议使用您的 GitHub 用户名或应用程序的名称作为 User-Agent 标头值。这使 GitHub 能够在出现问题时与您联系。

要对您的请求进行身份验证，您需要使用所需的范围或权限提供身份验证令牌。有几种不同的方法可以获取令牌：您可以创建个人访问令牌、使用 GitHub 应用程序生成令牌或在 GitHub Actions 工作流中使用内置的 GITHUB_TOKEN。有关更多信息，请参阅“对 REST API 进行身份验证”。

有关使用身份验证令牌的请求示例，请参阅“发出请求”。

本节演示如何使用 curl 对 GitHub REST API 发出经过身份验证的请求。

1. 设置

您必须在您的机器上安装 curl。要检查 curl 是否已安装，请在命令行上运行 curl --version。

• 如果输出提供了有关 curl 版本的信息，则表示 curl 已安装。
• 如果您收到类似于 command not found: curl 的消息，则表示 curl 未安装。下载并安装 curl。有关更多信息，请参阅curl 下载页面。

2. 为您的请求选择一个端点

1. 选择要发出请求的端点。您可以浏览 GitHub 的REST API 文档以发现可用于与 GitHub 交互的端点。

2. 确定端点的 HTTP 方法和路径。您将在请求中发送这些内容。有关更多信息，请参阅“HTTP 方法”和“路径”。

   例如，“创建问题”端点使用 HTTP 方法 POST 和路径 /repos/{owner}/{repo}/issues。

3. 识别任何必需的路径参数。必需的路径参数在端点路径中的花括号 {} 中显示。将每个参数占位符替换为所需的值。有关更多信息，请参阅“路径”。

   例如，“创建问题”端点使用路径 /repos/{owner}/{repo}/issues，路径参数为 {owner} 和 {repo}。要在 API 请求中使用此路径，请将 {repo} 替换为您想要创建新问题的存储库的名称，并将 {owner} 替换为拥有该存储库的帐户的名称。

3. 创建身份验证凭据

创建访问令牌以对您的请求进行身份验证。您可以保存您的令牌并将其用于多个请求。为令牌授予访问端点所需的任何范围或权限。您将在请求中使用 Authorization 标头发送此令牌。有关更多信息，请参阅“身份验证”。

4. 发出 curl 请求

使用 curl 命令发出请求。有关更多信息，请参阅curl 文档。

在您的请求中指定以下选项和值

• --request 或 -X 后跟 HTTP 方法作为值。有关更多信息，请参阅“HTTP 方法”。

• --url 后跟完整路径作为值。完整路径是一个 URL，其中包含 GitHub REST API 的基本 URL（https://api.github.com）和端点的路径，如下所示：https://api.github.com/PATH。将 PATH 替换为端点的路径。有关更多信息，请参阅“路径”。

  要使用查询参数，请在路径末尾添加 ?，然后以 parameter_name=value 的形式附加查询参数名称和值。用 & 分隔多个查询参数。如果您需要在查询字符串中发送数组，请对每个数组项使用一次查询参数，并在查询参数名称后附加 []。例如，要提供两个存储库 ID 的数组，请使用 ?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID。有关更多信息，请参阅“查询参数”。有关示例，请参阅“使用查询参数的请求示例”。

• --header 或 -H:

  • Accept：在 Accept 标头中传递媒体类型。要在 Accept 标头中传递多个媒体类型，请用逗号分隔媒体类型，例如：Accept: application/vnd.github+json,application/vnd.github.diff。有关更多信息，请参阅“Accept”和“媒体类型”。
  • X-GitHub-Api-Version：在 X-GitHub-Api-Version 标头中传递 API 版本。有关更多信息，请参阅“X-GitHub-Api-Version”。
  • Authorization：在 Authorization 标头中传递身份验证令牌。请注意，在大多数情况下，您可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果您传递的是 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。有关更多信息，请参阅“身份验证”。有关使用 Authorization 标头的请求示例，请参阅“使用主体参数的请求示例”。

• --data 或 -d 后跟 JSON 对象中的任何主体参数。如果您不需要在请求中指定任何主体参数，请省略此选项。有关更多信息，请参阅“主体参数”。有关示例，请参阅“使用主体参数的请求示例”。

请求示例

以下请求示例使用“获取 Octocat”端点以 ASCII 艺术形式返回 octocat。

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

使用查询参数的请求示例

“列出公共事件”端点默认返回三十个问题。以下示例使用 per_page 查询参数改为返回两个问题而不是 30 个，并使用 page 查询参数仅获取第一页结果。

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

使用主体参数的请求示例

以下示例使用“创建问题”端点在 octocat/Spoon-Knife 存储库中创建一个新问题。将 YOUR-TOKEN 替换为您在先前步骤中创建的身份验证令牌。

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

要查看状态代码和标头，请在发送请求时使用 --include 或 --i 选项。

例如，此请求获取 octocat/Spoon-Knife 存储库中的问题列表

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

它返回类似以下内容的状态代码和标头

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

在此示例中，响应代码为 200，表示请求成功。

例如，您可以使用 > 将响应重定向到文件。在以下示例中，将 REPO-OWNER 替换为拥有存储库的帐户的名称，将 REPO-NAME 替换为存储库的名称。

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

然后，您可以使用 jq 获取每个问题的标题和作者 ID

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

前两个命令返回类似以下内容

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

有关 jq 的更多信息，请参阅 jq 文档。