REST API 入门

简介

本文介绍如何通过 GitHub CLI、curl 或 JavaScript 使用 GitHub REST API。有关快速入门指南，请参阅 GitHub REST API 快速入门。

关于对 REST API 的请求

本节介绍构成 API 请求的元素：

HTTP 方法
Path
标头
媒体类型
身份验证
Parameters

每个对 REST API 的请求都包含一个 HTTP 方法和一个路径。取决于 REST API 终结点，可能还需要指定请求标头、身份验证信息、查询参数或正文参数。

REST API 参考文档介绍了每个终结点的 HTTP 方法、路径和参数。它还显示每个终结点的示例请求和响应。有关详细信息，请查看 REST 参考文档。

HTTP 方法

终结点的 HTTP 方法定义它对给定资源执行的操作类型。常见的一些 HTTP 方法有 GET、POST、DELETE 和 PATCH。 REST API 参考文档介绍了每个终结点的 HTTP 方法。

例如，“列出存储库问题”终结点的 HTTP 方法为 GET。

在可能的情况下，GitHub REST API 尽量为每个操作使用适当的 HTTP 方法。

GET：用于检索资源。
POST：用于创建资源。
PATCH：用于更新资源的属性。
PUT：用于替换资源或集合。
DELETE：用于删除资源。

路径

每个终结点都有一个路径。 REST API 参考文档介绍了每个终结点的路径。例如，“列出存储库问题”终结点的路径为 /repos/{owner}/{repo}/issues。

路径中的大括号 {} 表示需要指定的路径参数。路径参数修改终结点路径，在请求中是必需的。例如，“列出存储库问题”终结点的路径参数为 {owner} 和 {repo}。要在 API 请求中使用此路径，请将 {repo} 替换为想要请求问题列表的存储库的名称，并将 {owner} 替换为存储库所有者帐户的名称。

标头

标头包含有关请求和所需响应的其它信息。以下是可在对 GitHub REST API 的请求中使用一些标头示例。有关使用标头的请求示例，请参阅发出请求。

`Accept`

大多数 GitHub REST API 终结点指定应传递值为 application/vnd.github+json 的 Accept 标头。 Accept 标头的值为媒体类型。有关媒体类型的详细信息，请参阅媒体类型。

`X-GitHub-Api-Version`

应使用此标头指定要用于请求的 REST API 版本。有关详细信息，请参阅“API 版本”。

`User-Agent`

所有 API 请求都必须包含有效的 User-Agent 标头。 User-Agent 标头标识发出请求的用户或应用程序。

默认情况下，GitHub CLI 会发送有效的 User-Agent 标头。但是，GitHub 建议使用 GitHub 用户名或应用程序名称作为 User-Agent 标头值。这样，如果存在问题，GitHub 即可与你联系。

默认情况下，curl 会发送有效的 User-Agent 标头。但是，GitHub 建议使用用户名或应用程序名称作为 User-Agent 标头值。这样，如果存在问题，GitHub 即可与你联系。

如果使用的是 Octokit.js SDK，则该 SDK 为你发送有效的 User-Agent 标头。但是，GitHub 建议使用 GitHub 用户名或应用程序名称作为 User-Agent 标头值。这样，如果存在问题，GitHub 即可与你联系。

下面的示例 User-Agent 是一个名为 Awesome-Octocat-App 的应用：

User-Agent: Awesome-Octocat-App

没有 User-Agent 标头的请求将被拒绝。如果提供无效的 User-Agent 标头，则将收到 403 Forbidden 响应。

媒体类型

可以通过将媒体类型添加到请求的 Accept 标头来指定一种或多种媒体类型。有关 Accept 标头的详细信息，请参阅 Accept。

媒体类型指定要从 API 获取的数据格式。媒体类型特定于资源，允许它们独立更改并支持其他资源不支持的格式。每个 GitHub REST API 终结点的文档将描述它支持的媒体类型。有关详细信息，请参阅 GitHub REST API 文档。

GitHub REST API 支持的最常见媒体类型是 application/vnd.github+json 和 application/json。

还可以将自定义媒体类型和某些端点搭配使用。例如，用于管理提交和提取请求的 REST API 支持媒体类型 diff、patch 和 sha。某些其他端点使用媒体类型 full、raw、text 或 html。

GitHub 的全部自定义媒体类型类似于 application/vnd.github.PARAM+json，其中 PARAM 是媒体类型的名称。例如，要指定 raw 媒体类型，可以使用 application/vnd.github.raw+json。

有关使用媒体类型的请求示例，请参阅发出请求。

身份验证

许多终结点需要身份验证或是在进行身份验证后返回其他信息。此外，进行身份验证后，每小时可以发出更多请求。

要对请求进行身份验证，需要提供具有所需作用域或权限的身份验证令牌。有几种不同方式获取令牌：可以创建 personal access token，生成包含 GitHub App 的令牌，或使用 GitHub Actions 工作流中内置的 GITHUB_TOKEN。有关详细信息，请参阅“对 REST API 进行身份验证”。

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

注意

如果不想创建令牌，可以使用 GitHub CLI。 GitHub CLI 将自动进行身份验证，并帮助保护帐户的安全。有关详细信息，请参阅此页面的 GitHub CLI 版本。

警告

应该像对待密码或其他敏感凭据那样对待访问令牌。有关详细信息，请参阅“确保 API 凭据安全”。

尽管无需身份验证即可访问某些 REST API 终结点，但 GitHub CLI 要求先进行身份验证，然后才能使用 api 子命令发出 API 请求。使用 auth login 子命令向 GitHub 进行身份验证。有关详细信息，请参阅发出请求。

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

警告

应该像对待密码或其他敏感凭据那样对待访问令牌。有关详细信息，请参阅“确保 API 凭据安全”。

参数

许多 API 方法要求或允许在请求的参数中发送其他信息。有几种不同类型的参数：路径参数、正文参数和查询参数。

路径参数

路径参数会修改终结点路径。这些是请求中的必需参数：有关详细信息，请参阅 Path。

正文参数

正文参数使你可以将其他数据传递给 API。上述参数可以是可选参数，也可以是必需参数，具体取决于终结点。例如，正文参数可能允许在创建新问题时指定问题标题，或在启用/禁用功能时指定某些设置。每个 GitHub REST API 终结点的文档将描述它支持的正文参数。有关详细信息，请参阅 GitHub REST API 文档。

例如，“创建问题”终结点要求为请求中的新问题指定标题。此外，还允许选择指定其他信息，例如要放入问题正文中的文本、要分配给新问题的用户或要应用于新问题的标签。有关使用正文参数的请求示例，请参阅发出请求。

必须对请求进行身份验证才能传递正文参数。有关详细信息，请参阅身份验证。

若要向 GitHub 进行身份验证，请从终端运行以下命令。
```
gh auth login
```
可以使用 --scopes 选项指定所需的作用域。如果要使用创建的令牌进行身份验证，可以使用 --with-token 选项。有关详细信息，请参阅 GitHub CLI auth login 文档。
选择要进行身份验证的位置：
- 如果通过 GitHub.com 访问 GitHub，请选择“GitHub.com”****。
- 如果通过其他域访问 GitHub，请选择“其他”，然后输入主机名（例如 octocorp.ghe.com）****。
按照屏幕上的其余提示操作。

选择 HTTPS 作为 Git 操作的首选协议时，GitHub CLI 将自动存储 Git 凭据，并对询问是否要使用 GitHub 凭据向 Git 进行身份验证的提示回答“是”。此选项非常有用，因为这允许直接使用 git push、git pull 等 Git 命令，无需设置单独的凭据管理器或使用 SSH。

3. 为请求选择终结点

选择要向其发出请求的终结点。可以浏览 GitHub 的 REST API 文档，了解可用于与 GitHub 交互的终结点。
标识终结点的 HTTP 方法和路径。将随请求一起发送这些内容。有关详细信息，请参阅

Tool navigation

本文内容

简介