はじめに
GraphQL を初めて学習するにあたり、気になった点や疑問に思ったことを調査し、本記事にまとめました。
本記事の目的は、あくまで自身の疑問を解消し、GraphQL の概要を理解することにあります。
そのため、詳細な内容には触れてませんので、その点ご留意いただければと思います。
GraphQL とは
従来の REST API では、GET・POST・PUT・DELETE といったHTTP の動詞を使ってデータを操作 しますが、GraphQL では1 つのエンドポイントを通じて、必要なデータだけを取得・更新・削除できます。
GraphQL はなぜ生まれたの
私の推測も入っているのですが、GraphQL は REST API での課題を解決するために生まれたと考えています。
以下に、REST API の主な課題と、それに対する GraphQL の解決策を示します。
課題 1: オーバーフェッチとアンダーフェッチ
REST API では、決められたフォーマットでデータを取得します。
そのため、必要以上のデータを取得してしまう（オーバーフェッチ）ことや、必要なデータが取得できない（アンダーフェッチ）ことが発生する場合があります。
例: ユーザー名と投稿記事のタイトルを取得したい場合
GET /users/1
{
"id": 1,
"name": "Alice",
"email": "alice@example.com",
"phone": "123-456-7890"
}
"name"の情報がほしいだけなのに、"email"や"phone"の情報まで取得される。
"posts"の情報を手にいれるには、他のエンドポイントにリクエストを送る必要がある。
GraphQL の解決策
GraphQL では、必要なデータだけを取得できます。
ユーザー名および投稿記事のタイトルを取得したい場合、以下の 1 回のリクエストで取得できます。
query {
user(id: 1) {
name
posts {
title
}
}
}
課題 2: エンドポイントが多い
REST API では、取得したいデータに応じてエンドポイントを変更する必要があります。
エンドポイントの数が増えるほど、管理や変更の手間がかかります。
例：
GET /users/1 → ユーザー情報を取得
GET /users/1/posts → ユーザーの投稿一覧を取得
GraphQL の解決策
GraphQL では、エンドポイントが 1 つに統一されるため、取得するデータに応じてエンドポイントを変更する必要がありません。
エンドポイント：/graphql
クエリ：
query {
user(id: 1) {
name
posts {
title
}
}
}
GraphQL のメリット
上記に記載した内容と一部重複しますが、以下が GraphQL のメリットと考えてます。
- エンドポイントが 1 つであること
- 必要なデータを 1 回のクエリで取得することができること
- バージョン管理が不要なこと（スキーマ拡張で対応できるため）
- API のドキュメントを作成する必要がない（スキーマ定義することで自動で生成されるため）
GraphQL のデメリット
私は以下の面が GraphQL のデメリットであると考えています。
- 学習コストが高い：スキーマ定義やリゾルバーの実装が必要となり、設計が複雑になる。そのため、学習コストが高い。
- キャッシュ戦略が難しい：REST API では、エンドポイントごとにキャッシュを設定できるが、GraphQL ではすべてのデータが単一のエンドポイントから取得されるため、ブラウザや CDN でのキャッシュが難しくなる。
- パフォーマンス：GraphQL では過剰・大量なデータを取得される可能性があるため、パフォーマンスが低下する可能性がある。
- セキュリティ：GraphQL ではクライアントが自由にクエリを定義できる。REST API のようにエンドポイントごとに権限を設定する方法が使えないため、認可（Authorization）の管理が難しくなる。
GraphQL の仕組みを簡単に説明
スキーマでデータを定義し、リゾルバーを利用してデータ操作を行う。
- スキーマ: データの設計図。取得できるデータや指定できるフィールドを定義する。
- リゾルバー: 実際にデータを取得・処理する関数。
お店に例えると…
スキーマは 「商品カタログ」、リゾルバーは 「店員」。
お客さんが注文（クエリ）すると、店員さん（リゾルバー）がカタログをもとに商品（データ）を提供する、とイメージすると分かりやすいと思います。
REST と GraphQL どちらを使うか
GraphQL が適しているケース
GraphQL の特徴を考慮した結果、以下の場合は GraphQL の方が適していると考えています。
- SPA（シングルページアプリケーション）などで通信量を減らしたい場合
→ 必要なデータだけを取得できるため、不要なデータのやり取りが発生しにくい。 - 複数のデータを 1 回のリクエストで取得したい場合
→ 複数のリソースを 1 つのエンドポイントから取得でき、リクエスト回数を減らせる。 - API の柔軟性が求められる場合
→ クライアント側で取得するデータの内容を自由に指定でき、拡張性が高い。
REST が適しているケース
一方で、以下のようなケースでは REST の方が適している考えてます。
- 小規模なアプリケーションなど、シンプルな API 設計で十分な場合
→ REST は設計が直感的で理解しやすく、実装の負担が少ない。 - 画像や静的データの提供など、CDN キャッシュを活用したい場合
→ REST は HTTP キャッシュとの相性が良く、CDN を活用しやすいため、負荷を軽減できる。
終わりに
本当は、設計についても学習して記載したかったのですが、理解に時間がかかりそう記事が長くなりそうなので、またの機会にします。
今回の記事がどなたかの参考になれば幸いです。