GraphQL

GraphQL とは

GraphQL は API のためのクエリ言語であり、その問い合わせを処理する仕組みです。REST が「URL（エンドポイント）ごとに決まった形のデータを返す」のに対し、GraphQL はクライアントが欲しいデータの形を指定します。

通常、エンドポイントは 1 つ（例: /graphql）だけ。クライアントはそこへ「どのフィールドが欲しいか」を書いたクエリを送り、サーバはその形のまま返します。

• データの**型（スキーマ）**をサーバが定義し、契約として公開する。
• クライアントはスキーマの範囲で、必要な部分だけを要求する。

クエリの書き方

クエリは「欲しいフィールドを入れ子で書く」だけです。返ってくる JSON は、クエリの構造とほぼ同じ形になります。

query {
  user(id: "u123") {
    name
    posts(last: 3) {
      title
      comments {
        body
      }
    }
  }
}

このクエリ 1 本で、ユーザー名・直近 3 件の投稿タイトル・各投稿のコメント本文までまとめて取得できます。REST なら「ユーザー取得 → 投稿一覧取得 → 各投稿のコメント取得」と複数回叩く場面です。

データを書き換えるときは mutation、サーバからの継続的な更新を受け取るときは subscription を使います（後者は WebSocket 等の上で動くことが多い）。

REST との違い

最大の違いは「データの形を誰が決めるか」です。REST はサーバ（エンドポイント）が決め、GraphQL はクライアント（クエリ）が決めます。

観点	REST	GraphQL
エンドポイント	リソースごとに複数	原則 1 つ（/graphql）
取得データの形	サーバが固定で決める	クライアントがクエリで指定
過不足取得	起きやすい	必要分だけで解消しやすい
型・仕様	別途ドキュメントで管理	スキーマが型付きで自己記述
HTTP キャッシュ	URL 単位で効かせやすい	そのままでは効きにくい

REST でありがちな 2 つの無駄を、GraphQL は次のように解消します。

• 取りすぎ（over-fetching）：名前だけ欲しいのに巨大なユーザーオブジェクト全体が返る → 欲しいフィールドだけ書く。
• 足りない（under-fetching）：1 画面を作るのに複数エンドポイントを順番に叩く（N+1 リクエスト）→ 1 クエリにまとめる。

利点

GraphQL がもたらす主なメリットです。

• 過不足のない取得：必要なフィールドだけを 1 回で取れ、通信量とラウンドトリップを減らせる。
• 型付きスキーマ：API が自己記述的になり、補完・検証・ドキュメント生成が効く。
• フロント主導の開発：バックエンドのエンドポイント追加を待たずに、クライアント側で必要な形を組み立てられる。
• バージョニングしにくさの緩和：フィールド追加で拡張でき、/v2 のような大きな版上げが起きにくい。

注意点

便利さの裏にトレードオフがあります。導入前に把握しておきましょう。

• キャッシュが難しい：多くがエンドポイント 1 つへの POST のため、URL ベースの HTTP キャッシュ・CDN が素直に効かない。クライアント側キャッシュ（正規化）やパーシステッドクエリで補う。
• サーバ実装の複雑さ：リゾルバ設計を誤ると、深い入れ子でN+1 問題（1 件ごとに DB を叩く）が起きやすい。DataLoader 等でまとめる工夫が要る。
• コストの読みにくさ：任意の深い・重いクエリを投げられるため、クエリの深さ・複雑度の制限やタイムアウトが必要。
• エラーとステータス：エラーでも HTTP 200 を返し、本文の errors に詰める設計が一般的で、監視の作法が REST と異なる。

データ取得の対比として REST API を、リアルタイムな subscription の土台として WebSocket もあわせて読むと位置づけが明確になります。