GitHub の REST API と GraphQL API の比較

GitHub の API について

GitHub には、REST API と GraphQL API という 2 つの API が用意されています。 どちらの API も、GitHub CLI、curl、公式の Octokit ライブラリ、サード パーティ製ライブラリを使って操作できます。 一方の 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 は、要求したものより多くのデータを返し、事前に決定されている構造でそれを返します。 また、複数の REST API 要求と同じ処理を、1 つの GraphQL 要求で実現することもできます。 行う要求の数とフェッチするデータの量を減らすことができるので、GraphQL はモバイル アプリケーションの開発者に適しています。

たとえば、自分の 10 人のフォロワーの GitHub Enterprise Server ログインと、各フォロワーの 10 人のフォロワーのログインを、次のような 1 つの要求を送信して取得できます。

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

応答は、要求の構造に従った JSON オブジェクトになります。

これに対し、この同じ情報を REST API から取得するには、最初に GET /user/followers に対して要求を行う必要があります。 この API からは、各フォロワーのログインと、フォロワーに関する他の必要のないデータが返されます。 次に、各フォロワーについて、GET /users/{username}/followers に要求する必要があります。 全体では、1 回の GraphQL 要求から取得できるのと同じ情報を取得するために、要求を 11 回行う必要があり、余分なデータを受け取ります。

REST API の選択

REST API は GraphQL API より長く使われているため、一部の開発者は REST API に慣れている場合があります。 REST API では HTTP の標準の動詞と概念が使われるため、多くの開発者は REST API を使うための基本的な概念を既によく知っています。

たとえば、octocat/Spoon-Knife リポジトリに issue を作るには、JSON 要求を本文にして POST /repos/octocat/Spoon-Knife/issues に要求を送信する必要があります。

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

これに対し、GraphQL API を使って issue を作るには、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
    }
  }
}