GraphQL とは

GraphQL (グラフキューエル、グラフQL) とは、API (アプリケーション・プログラミング・インタフェース向けのクエリ言語とサーバーサイドのランタイムの両方を指します。GraphQL は、クライアントがリクエストしたデータのみを返すことを優先します。

GraphQL は、API の速度、柔軟性、開発者にとっての使いやすさを向上させるために設計されました。GraphiQL と呼ばれる統合開発環境 (IDE) にデプロイすることもできます。GraphQL は REST の代わりに、データを複数のデータソースから取得するリクエストを 1 つの API 呼び出しで構成できます。

さらに、GraphQL によって、既存のクエリに影響を与えずに、フィールドを追加したり、その使用を停止したりできるため、API の柔軟な保守が可能です。開発者は API を任意の方法で構築することができ、構築された API は GraphQL の仕様に基づいて、クライアントに対して予測可能な仕方で動作します。

API 開発者は GraphQL を使用してスキーマを作成し、クライアントがこのサービスを通じてクエリできるすべてのデータを記述します。

GraphQL スキーマはオブジェクトタイプで構成され、どの種類のオブジェクトをリクエストでき、どのフィールドを指定できるかを定義します。

クエリを受け取ると、GraphQL はクエリをスキーマに照合して検証し、検証されたクエリを実行します。

API 開発者は、スキーマの各フィールドにリゾルバーという関数を割り当てます。実行中にリゾルバーが呼び出されて値を生成します。

API クエリ (graphql-spec リポジトリで概説) の構文の定義と検証を除くと、その他のほとんどの決定は API 設計者に任されます。GraphQL は、データの保管方法や使用するプログラミング言語などを指定しないため、開発者は PHP (graphql-php)、Scala (Sangria)、Python (Graphene Python)、Ruby (graphql-ruby)、JavaScript (graphql.js) などを自由に使用できます。また、GraphQL にはネットワーク、認証、ページングに関する要件もありまん。

クライアント側から、最もよく利用される GraphQL の操作はクエリとミューテーションです。これらを CRUD モデルの create (作成)、read (読み取り)、update (更新)、delete (削除) と比較すると、クエリは read (読み取り) に相当します。ミューテーションがその他すべて (create、update、delete) に対応します。

GraphQL をビジネス環境やエンタープライズ環境で試してみようという場合は、その長所と短所を検討してください。

メリット

• GraphQL スキーマは GraphQL アプリケーションに単一のソースを設定します。組織には API 全体をフェデレーションする方法が提供されます。
• GraphQL 呼び出しは 1 回のラウンドトリップで処理されます。クライアントはリクエストしたものを取得し、余分なものは取得しません。
• データ型はしっかり定義されているので、クライアントとサーバー間の食い違いが発生するリスクが減少します。
• GraphQL ではイントロスペクションが可能であり、クライアントは、利用できるデータ型のリストをリクエストできます。これは自動生成文書に最適です。
• GraphQL では、既存のクエリを壊さずにアプリケーション API を進化させることができます。
• 数多くのオープンソース GraphQL 拡張機能が利用可能であり、REST API にはない機能を提供しています。
• GraphQL は特定のアプリケーション・アーキテクチャにとらわれません。既存の REST API 上に導入して、既存の API 管理ツールと連携できます。

デメリット

• REST API に慣れている開発者の場合、GraphQL を学習する一定期間が必要になります。
• GraphQL ではデータクエリ処理の多くがサーバーサイドに移行されるので、サーバー開発者の作業が複雑になります。
• 実装方法によっては、REST API とは異なる API 管理戦略が必要になります (とくに、レート制限や価格設定を考慮する必要がある場合は異なる戦略が必要です)。
• キャッシュが REST よりも複雑になります。
• API の保守担当者には、保守可能な GraphQL スキーマを作成する作業を追加で行う必要があります。

GraphQL クエリのサンプル

GraphQL を理解する上で、クエリと応答の例をいくつか見るのが効果的です。GraphQL プロジェクト Web サイトである graphql.org のサンプルをベースとした、3 つのサンプルをご覧ください。

最初のサンプルでは、クライアントが GraphQL クエリを構築し、指定した形式で特定のフィールドを返すように API に要求しています。

{
  me {
    name
  }
}

GraphQL API から、次のような結果が JSON 形式で返されます。

{
  "me": {
    "name": "Dorothy"
  }
}

次のサンプルが示すように、クライアントは GraphQL クエリの一部として引数を渡すこともできます。

{
  human(id: "1000") {
    name
    location
  }
}

次のような結果になります。

{
  "data": {
    "human": {
      "name": "Dorothy,
      "location": "Kansas"
    }
  }
}

ここからが、GraphQL の興味深い部分です。GraphQL では、ユーザーは再利用可能なフラグメントを定義して変数を割り当てることができます。

たとえば、ID のリストをリクエストして、各 ID に対する一連のレコードをリクエストする必要があるとします。GraphQL なら、必要なすべてを 1 つの API 呼び出しで取得するクエリを構築できます。

クエリは次のようになります。

query HeroComparison($first: Int = 3) {
  leftComparison: hero(location: KANSAS) {
    ...comparisonFields
  }
  rightComparison: hero(location: OZ) {
    ...comparisonFields
  }
}
fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

次のような結果になります。

{
  "data": {
    "leftComparison": {
      "name": "Dorothy",
      "friendsConnection": {
        "totalCount": 4,
        "edges": [
          {
            "node": {
              "name": "Aunt Em"
            }
          },
          {
            "node": {
              "name": "Uncle Henry"
            }
          },
          {
            "node": {
              "name": "Toto"
            }
          }
        ]
      }
    },
    "rightComparison": {
      "name": "Wizard",
      "friendsConnection": {
        "totalCount": 3,
        "edges": [
          {
            "node": {
              "name": "Scarecrow"
            }
          },
          {
            "node": {
              "name": "Tin Man"
            }
          },
          {
            "node": {
              "name": "Lion"
            }
          }
        ]
      }
    }
  }
}

GitHub をご利用の場合は、GitHub の GraphQL Explorer で GraphQL の実践的な処理を簡単に体験できます。

GraphQL は Facebook が開発したもので、2012 年にモバイルアプリケーション向けに使用が開始されました。GraphQL 仕様は 2015 年にオープンソース化されました。今では、GraphQL Foundation が管理しています。

GraphQL を活用しているオープンソース・プロジェクトは多岐にわたります。GraphQL の採用を促進しているプロジェクトの一部は、以下の通りです。

• Apollo：フロントエンド・クライアント・ライブラリ (Apollo Client) とバックエンド・サーバー・フレームワーク (Apollo Server) を含む GraphQL プラットフォーム
• Offix：アプリケーションに到達できない場合でも GraphQL ミューテーションとクエリを実行可能にする、オフラインクライアント
• Graphback：GraphQL 対応 Node.js サーバーを生成する、コマンドラインクライアント
• OpenAPI-to-GraphQL：OpenAPI 仕様で規定される API または Swagger を GraphQL に変換する、コマンドラインインタフェースとライブラリ