REST と GraphQL、どちらを選びますか

REST の強み

REST は、「利用者」「注文」のような資源ごとに住所 (URL) を決め、HTTP のメソッド (GET、POST など) で操作する作り方です。住所と操作が HTTP の決まりに沿っているので、読む人に分かりやすく、道具もそろっています。

特に、GET の応答はブラウザや CDN (利用者の近くで応答を配る中継の仕組み) にそのまま覚えさせやすい、という強みがあります。同じ住所への同じ問い合わせなら、サーバーまで行かずに返せます。

GraphQL が効く場面

GraphQL は、1 つの窓口に「この項目とこの項目が欲しい」と問いを送り、その形のまま受け取る作り方です。

たとえば、一覧の画面では名前だけ、詳しい画面では名前と住所と注文の履歴が欲しい、とします。REST で 1 つの住所しか用意していないと、一覧では要らない項目まで来ます (取りすぎ)。逆に、利用者と注文を別の住所で取るなら、何度も呼ぶことになります (足りなさ)。

GET /users/7
GET /users/7/orders

GraphQL なら、1 回の問いで欲しい形を指定できます。

query {
  user(id: 7) {
    name
    orders { id total }
  }
}

スマホの画面と PC の画面で欲しい項目が大きく違う、画面の数が多く毎回専用の住所を足すのがつらい、といったときに効きます。

トレードオフ

GraphQL にも弱点があります。

• キャッシュが効きにくい 1 つの窓口へ POST で問いを送ることが多く、HTTP のキャッシュをそのままは使いにくいです。クライアント側のキャッシュの仕組みを別に用意することになります
• 重い問いを送られやすい深く入れ子にした問いで、サーバーが重くなることがあります。問いの深さや重さに上限を付けます
• サーバー側で N+1 が起きやすい項目ごとに DB を引くと問い合わせが増えます。まとめて取る仕組み (DataLoader など) で防ぎます
• 権限を項目ごとに考える 1 つの窓口から何でも取れるので、どの項目を誰に見せてよいかを丁寧に決めます

だから、画面が少なく形が安定しているなら REST、画面ごとの違いが大きく、上の手間を払ってでも柔軟さが欲しいなら GraphQL、と決めます。

型をそろえたいだけなら、REST のまま OpenAPI (API の仕様を書く決まった形) から TypeScript の型を作る手や、サーバーもクライアントも TypeScript なら tRPC で関数のように呼ぶ手もあります。

話すときは、自分が関わったサービスの例を 1 つ用意します。たとえば「画面は数枚で形も決まっていたので REST にし、OpenAPI から型を作ってフロントエンドとそろえた」のように、選んだ条件と一緒に話します。