比较 GitHub 的 REST API 与 GraphQL API

关于 GitHub 的 API

GitHub 提供两种 API：REST API 和 GraphQL API。您可以使用 GitHub CLI、curl、官方 Octokit 库以及第三方库与这两种 API 交互。有时，某些功能可能仅在某个 API 上受支持，而在另一个 API 上不可用。

您应当使用最符合需求且最熟悉的 API。无需在两者之间专属使用某一种 API。Node ID 让您可以在 REST API 与 GraphQL API 之间切换。更多信息，请参阅 使用全局 Node ID。

本文讨论了每种 API 的优势。有关 GraphQL API 的更多信息，请参阅 关于 GraphQL API。有关 REST API 的更多信息，请参阅 关于 REST API。

选择 GraphQL API

GraphQL API 只返回您请求的确切数据。GraphQL 还根据您的请求以预先已知的结构返回数据。相比之下，REST API 会返回超出您请求的额外数据，并以预定义的结构返回。您还可以在一次 GraphQL 请求中实现相当于多次 REST API 请求的功能。请求次数更少、获取的数据更少的能力，使 GraphQL 对移动应用开发者具有吸引力。

例如，要获取您十位关注者的 GitHub 登录名，以及每位关注者的十位关注者的登录名，您可以发送如下单个请求：

{
  viewer {
    followers(first: 10) {
      nodes {
        login
        followers(first: 10) {
          nodes {
            login
          }
        }
      }
    }
  }
}

响应将是一个遵循您请求结构的 JSON 对象。

相比之下，要通过 REST API 获取相同信息，您需要先请求 GET /user/followers。API 将返回每个关注者的登录名以及您不需要的其他关注者数据。随后，对每个关注者，您需要再请求 GET /users/{username}/followers。总计，您需要发起 11 次请求才能获取与一次 GraphQL 请求相同的信息，并且会收到多余的数据。

选择 REST API

由于 REST API 的历史比 GraphQL API 更悠久，一些开发者对 REST API 更为熟悉。REST API 使用标准的 HTTP 方法和概念，许多开发者已经熟悉使用 REST API 所需的基本概念。

例如，要在 octocat/Spoon-Knife 仓库创建一个议题，您需要向 POST /repos/octocat/Spoon-Knife/issues 发送带有 JSON 请求体的请求。

{
  "title": "Bug with feature X",
  "body": "If you do A, then B happens"
}

相比之下，要通过 GraphQL API 创建议题，您需要先获取 octocat/Spoon-Knife 仓库的节点 ID，然后发送类似以下的请求：

mutation {
  createIssue(
    input: {
      repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
      title: "Bug with feature X"
      body: "If you do A, then B happens"}
  ) {
    issue {
      number
      url
    }
  }
}