比较 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，可减少发出的请求数和提取的数据，这使得其对于移动应用程序开发人员极具吸引力。

例如，若要获取你的 10 个关注者的 GitHub Enterprise Cloud 登录名，以及其中每个关注者的 10 个关注者的登录名，可以发送一个如下所示的请求：

{
  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 存储库中创建问题，需要使用 JSON 请求正文向 POST /repos/octocat/Spoon-Knife/issues 发送请求：

{
  "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
    }
  }
}