比较 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
    }
  }
}