REST と GraphQL — 何を楽にして、何を難しくするか

What — 同じ画面を作るときの違い

GET /articles/123
GET /articles/123/author
GET /articles/123/comments?limit=10

→ 3往復（HTTP/2 なら並列で流せる）
→ それぞれ独立に CDN キャッシュできる
→ 使わないフィールドも返る（オーバーフェッチ）
→ 足りなければもう1回呼ぶ（アンダーフェッチ）

GraphQL が持ち込む3つの責任

Why — どちらが優れているかではない

GraphQL は2012年に Facebook が作りました。動機は明確で、モバイルアプリの画面ごとに必要なデータが違いすぎたことです。

• 画面が増えるたびに専用エンドポイントを作ると、API が増え続ける
• 汎用エンドポイントにすると、どの画面でも使わないデータまで返る
• モバイルの回線は遅く、往復も転送量も削りたい
• アプリのバージョンによって必要なフィールドが違う

**「クライアントが必要なものを宣言する」**という発想は、この状況への合理的な回答でした。

しかし、その柔軟性はサーバーが持っていた制御権をクライアントに渡すことで得られています。渡した分だけ、制御の責任がサーバー側に残ります。

「REST は往復が多い」への反論

REST の欠点として挙げられる往復回数は、BFF（Backend For Frontend）でかなり解消できます。

GET /screens/article-detail?id=123
  → 記事 + 著者 + コメント10件を1回で返す

画面ごとに専用のエンドポイントを作る形です。往復は1回、転送量も過不足なし。GraphQL の利点の多くがここで得られます。

代償は「画面が増えるたびにエンドポイントが増える」こと。画面の種類が少なく、変更頻度も低いなら、BFF のほうが単純で安全です。

画面が数十種類あり、クライアントが複数（Web / iOS / Android / 提携先）ある場合に、GraphQL の価値が出てきます。

エラーとステータスコード

GraphQL は原則として HTTP 200 を返し、エラーは errors 配列で表現します。

HTTP 200 OK
{
  "data": { "article": null },
  "errors": [{ "message": "Not found", "path": ["article"] }]
}

これはエラー設計の章で見た「すべて 200 で返す」問題そのものです。監視・ロードバランサ・CDN が異常を検知できません。 GraphQL を採用するなら、エラー率の監視を errors 配列を見る形で作り直す必要があります。

演習 — まず自分で判断する

解説を読む前に、まず自分で判断してみてください。ここで一度詰まっておくと、 次の節の判断軸が「なるほど」ではなく「そう来たか」に変わります。