比较 GitHub 的 REST API 和 GraphQL API

关于 GitHub 的 API

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

您应该使用最符合您的需求且您最习惯使用的 API。您无需专门使用其中一个 API。节点 ID 允许您在 REST API 和 GraphQL API 之间切换。有关更多信息，请参阅 "使用全局节点 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
    }
  }
}