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 は、要求に基づいて、既知の構造でデータを返します。これに対し、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
    }
  }
}

この記事の内容

GitHub の API について

GraphQL API の選択

REST API の選択