LASSIC Media らしくメディア

LASSIC IT事業部｜元請（プライムベンダー）としてシステム保守・運用を受託

GraphQLとRESTの違い — 単一エンドポイントと型システムが変えること

GraphQL API開発・REST移行を外注で進めるとは、Facebookが2015年9月に仕様と参照実装（graphql.js）を公開したクエリ言語を用いたAPI設計・実装業務を、専門知識を持つ外部パートナーに委ねる取り組みです^*1。

REST（Representational State Transfer）は、リソースごとにURLエンドポイントを設ける設計スタイルです。たとえばユーザー情報は /users/{id}、注文一覧は /orders のように、リソースの種類と操作（GET/POST/PUT/DELETE）をURLと HTTPメソッドの組み合わせで表現します。

GraphQLは異なるアプローチを取ります。エンドポイントは原則として1つだけ（例：/graphql）で、クライアントが「どのフィールドを、どの深さで取得するか」をクエリ文字列として指定します。サーバーはスキーマ（型定義）に従ってそのクエリを解釈し、過不足なくデータを返します。

この違いがもたらす実務上の差は大きく3点あります。

第一に、一度のリクエストで複数リソースを取得できます。RESTでは「ユーザー情報を取ってから注文リストを取る」という2回のリクエストが必要な場面でも、GraphQLクエリなら1回で解決できます。

第二に、型システムとスキーマがAPIの契約として機能します。GraphQL仕様（October 2021版）では、スカラー型（String・Int・Float・Boolean・ID）、オブジェクト型、リスト型などが厳密に定義されており、スキーマ自体がドキュメントになります。

第三に、バージョニング管理がしやすくなります。フィールド単位で廃止予定（deprecated）を宣言できるため、APIのメジャーバージョンを上げずに変更を積み上げられます。

ただし、GraphQLがRESTより優れているという単純な話ではありません。RESTは広く普及しており、HTTPキャッシュとの相性もよく、単純なCRUD操作や公開APIには引き続き適しています。GraphQLは「クライアントが多様なデータ形状を要求するBtoB SaaS」「モバイルアプリとWebが同じAPIを共用する状況」「フロントエンド開発速度を上げたいとき」に向いています。

オーバーフェッチ・アンダーフェッチの解消とN+1問題への対処

GraphQLが解決する課題として、まずオーバーフェッチとアンダーフェッチがあります。

オーバーフェッチとは、クライアントが必要としていないデータまでレスポンスに含まれることです。REST APIで /users/{id} を叩くと、画面に表示するのは氏名とメールアドレスだけなのに、生年月日・住所・更新日時なども返ってくるケースが典型です。モバイル回線では不要なペイロードが通信コストとバッテリー消費に直結します。

Facebookがモバイルアプリ向けにGraphQLを開発した背景もここにあります。2012年のiOS・Androidアプリ再構築時、既存のREST APIでは「サーバーが用意するデータ形状」と「アプリが必要とするデータ形状」のズレが深刻でした^*1。

アンダーフェッチとは逆に、1回のリクエストでは必要なデータが揃わず、複数回リクエストを発行しなければならない状態です。たとえば、記事一覧を取得してから各記事に紐づく著者情報を別途取得するパターンがそれに当たります。

GraphQLではクライアントが必要なフィールドをクエリで指定するため、この2つの問題を構造的に解消できます。

N+1問題とDataLoader

ただし、GraphQLには固有の落とし穴があります。それがN+1問題です。

リスト（例：10件の記事）を返すクエリで、各アイテムの関連データ（著者情報）をリゾルバ内で個別に取得すると、「リスト取得1回＋著者取得10回＝11回」のDBクエリが発行されます。アイテム数がNなら合計N+1回になることから、この名前がついています。

対処策として広く使われるのがDataLoaderです。Facebookが2010年に開発した「Loader」APIをベースにしたJavaScriptユーティリティで、単一イベントループ内の個別ロード要求をまとめてバッチ処理します^*2。DataLoaderのドキュメントでは「単純な実装で4回の往復が必要な場合も、2往復程度に削減できる」と説明されています^*2。GraphQLリゾルバ内でDataLoaderを使うことで、N+1を実質的に解消できます。

外注先にDataLoaderの採用を前提とする旨をRFP（提案依頼書）に明記することで、パフォーマンス設計の抜け漏れを防げます。

スキーマ設計 — 外注前に社内で握るべき3つの決定事項

GraphQL開発で社内が押さえるべき核心はスキーマ設計です。スキーマはAPIの契約であり、一度クライアントに公開すると変更コストが高くなります。外注先に丸投げすると、後から業務ルールと合わない型定義に気づき、大規模な修正が発生するリスクがあります。

決定事項1：ドメインモデルとの対応

GraphQLのオブジェクト型（Object Type）は業務ドメインの概念に対応させます。「注文」「顧客」「商品」といった業務エンティティと型定義を1対1で対応づける設計が、長期的な保守性を高めます。

GraphQL仕様（October 2021版）では、スキーマ定義言語（SDL）を使って型とフィールドを明示的に定義します。例えば type User { id: ID! name: String! email: String! } のように、フィールド名・型・必須/任意（!は必須）を宣言します。

決定事項2：QueryとMutation、Subscriptionの境界

GraphQLは操作を3種類に分類します。Query（データ取得）、Mutation（データ変更）、Subscription（サーバー起点のリアルタイム更新）です。リアルタイム要件があるかどうか、WebSocketを扱うインフラ体制があるかを先に確認してから、外注スコープに含めるか判断します。

決定事項3：フィールドの廃止方針

GraphQL仕様では @deprecated ディレクティブでフィールドを廃止予定とマークできます。廃止フィールドをいつ削除するか、クライアントへの通知方法をあらかじめ決めておくと、外注先がスキーマの進化戦略を立てやすくなります。

RESTからGraphQLへの段階的移行 — 併存・BFF・ラッパーの3パターン

既存のREST APIをGraphQLに切り替える場合、一度にすべてを置換することはリスクが高く、現実的でありません。実務では3つのパターンが使われます。

パターン1：REST併存（Thin GraphQL Layer）

既存のRESTエンドポイントはそのままに、GraphQLレイヤーを薄く被せます。GraphQLリゾルバが内部でREST APIを呼び出す形です。Apollo Serverはこの構成を「段階的な採用（incremental adoption）」として推奨しており、既存インフラを壊さずGraphQLを試せます^*3。

メリットは移行リスクの低さです。GraphQLが期待通りに動かなければREST側に戻せます。デメリットは、REST呼び出しのオーバーヘッドが残ることとN+1が発生しやすい点です。DataLoaderと組み合わせて対処します。

パターン2：BFF（Backend for Frontend）

BFF（Backend for Frontend）とは、フロントエンドの種類（Web・モバイル・TV等）ごとに専用のバックエンドサービスを置くアーキテクチャパターンです。BFFをGraphQLで実装し、その後ろに既存のREST APIやマイクロサービスを配置します。

フロントエンドチームが独立してスキーマを変更でき、バックエンドへの影響を最小化できます。BFFのGraphQL実装部分を外注し、既存RESTは内製のまま維持するという切り分けもしやすいパターンです。

パターン3：段階的移管（Strangler Fig パターン）

Strangler Figパターンとは、既存システムを少しずつ新しい実装に置き換えていく移行手法です。まず新規機能をGraphQLで実装し、既存機能を順次GraphQL化していきます。最終的にREST APIは廃止されます。

完全移行を目指す場合に向いていますが、移行期間中は2系統を維持するコストがかかります。外注先に移行チェックリストとフェーズ定義を求めると、進捗管理がしやすくなります。

認可・レート制限・キャッシュ・計測 — 見落とされやすい4つの運用設計

GraphQLは柔軟性が高い反面、RESTとは異なる運用上の注意点があります。外注先への要件漏れが起きやすい4つの設計ポイントを押さえておきます。

1. フィールドレベルの認可設計

RESTでは「このエンドポイントにアクセスできるロール」で認可を管理します。GraphQLは単一エンドポイントなので、フィールド単位で認可を制御する必要があります。Apollo Serverではリゾルバ内のコンテキスト（contextValue）にユーザー情報を渡し、各フィールドのリゾルバで権限チェックします^*4。

認可ロジックが複数のリゾルバに散在すると保守が難しくなります。外注先に「認可はモデル層（データソース層）に集約する」方針を示すと、コードの一貫性を保ちやすくなります。

2. レート制限とクエリ複雑度の制御

GraphQLクエリはネストを深くすることで意図せず大量のデータを要求できます。例えば「ユーザー一覧の各ユーザーの投稿一覧の各投稿のコメント一覧」のように再帰的に展開すると、DBへの負荷が指数的に増加します。

対策としてクエリの複雑度（complexity）を計算し、閾値を超えるクエリを拒否する仕組みを設けます。Apollo Serverでは introspection を本番環境で無効化（false）することも推奨されており、スキーマ情報の意図しない公開を防げます^*3。

3. HTTPキャッシュへの対応

GraphQLは通常POSTリクエストで送信されるため、ブラウザキャッシュやCDNの標準的なHTTPキャッシュが機能しません^*5。対策は3つあります。

• Automatic Persisted Queries（APQ）：クエリをサーバー側で登録し、短縮ハッシュIDをGETで送信することでCDNキャッシュを利用できます
• フィールドレベルのキャッシュ制御：スキーマの各フィールドに maxAge と scope を設定し、レスポンス全体のキャッシュ有効期限を計算します
• アプリケーション内キャッシュ：Redisなどを使ったサーバーサイドキャッシュで頻繁に使われるクエリ結果を保持します

4. クエリ計測とオブザーバビリティ

RESTでは「エンドポイントごとのレスポンスタイム」を計測すれば十分でした。GraphQLでは同一エンドポイントに多様なクエリが来るため、クエリ単位での計測が必要です。どのフィールドが頻繁に使われているか、どのクエリが遅いかを可視化する手段を外注先に要件として伝えます。

外注の進め方と委託範囲 — スキーマ設計は社内、実装は外部が基本線

GraphQL API開発の外注化では、「何を社内で決め、何を委託するか」の切り分けが成否を左右します。スキーマ設計と認可方針は業務知識が必要な領域であり、外部任せにするとビジネスロジックとAPIの整合が取れなくなるリスクがあります。

社内で担うべき範囲

• ドメインモデルとスキーマの対応定義：どのエンティティをどのGraphQL型に対応させるかは業務部門との合意が必要です
• 認可ポリシーの決定：ロールごとのアクセス可能フィールドの一覧を社内で確認します
• 移行フェーズの判断：どの機能をいつGraphQL化するかは事業側の優先度判断です

外注に委託できる範囲

• スキーマのSDL実装と検証：SDL（スキーマ定義言語）への落とし込みと、テストツールを使った整合性検証
• リゾルバの実装とDataLoader組み込み：N+1対策を含むデータ取得ロジックの実装
• CI/CDパイプラインの整備：スキーマ変更の差分検出（スキーマBreaking Change検査）の自動化
• キャッシュ・レート制限の実装：Apollo ServerのAPQ設定、複雑度制限の実装
• 移行スクリプトと並走テスト：REST→GraphQLの応答一致確認テストの作成

外注先選定で確認すべき技術スタック

GraphQL API開発に必要な技術領域は広く、内製で揃えるには相当の時間がかかります。Node.js（Apollo Server 4）またはPython（Strawberry/Graphene）、Java/Kotlin（DGS Framework）、C#（graphql-dotnet）など言語別に主要な実装ライブラリが存在します。

外注先に確認すべきスキルセットとして、GraphQL SDL・リゾルバ実装・DataLoader・認証/認可設計・クエリ複雑度制御・CI/CD（スキーマ差分検出）の6領域が挙げられます。これらをすべて保有するエンジニアを個人で抱えるのは現実的でなく、チームとして揃えるためにも外部パートナーを活用するメリットがあります。

仕様認識のズレによるスキーマの大幅修正は、本番リリース直前に発覚すると開発期間が数週間単位で延びるリスクがあります。RFP段階でサンプルスキーマと業務要件を共有し、提案時にスキーマ案を返してもらうことで、認識の一致を事前に確認できます。

まとめ：GraphQL外注成功の3つの判断軸

本稿では、GraphQL API開発とREST移行を外注で進める実務ポイントを整理しました。要点を3点に集約します。

第一に、GraphQLはRESTの置き換えではなく、複数クライアントから多様なデータ要求が来る状況への解決策です。単一エンドポイント・型システム・クライアント主導のクエリという3つの特徴がオーバーフェッチ・アンダーフェッチを解消しますが、N+1問題とHTTPキャッシュへの対応は別途設計が必要です。

第二に、REST移行は「ラッパー・BFF・段階的移管」の3パターンから事業優先度と既存インフラの状況に応じて選択します。一度にすべてを置換するのではなく、フェーズを分けてリスクを分散させることが重要です。

第三に、外注化の成否はスキーマ設計と認可ポリシーを社内で握れるかにかかっています。実装・テスト・CI/CDの整備は外部に委ねられますが、業務ルールに根ざしたスキーマ定義は社内の意思決定が不可欠です。

よくある質問

著者：テレリモ総研編集部　鈴木 亮佑

ご不明な点はお問い合わせフォームからもご連絡いただけます。

1. *1　出典：Meta Engineering「GraphQL: A data query language」（2015年）
2. *2　出典：graphql/dataloader GitHub リポジトリ（https://github.com/graphql/dataloader）（確認：2026年）
3. *3　出典：Apollo GraphQL「Apollo Server Documentation」（確認：2026年）
4. *4　出典：Apollo GraphQL「Authentication and authorization」（確認：2026年）
5. *5　出典：Apollo GraphQL「Caching」（確認：2026年）

Tweet