GraphQL — 欲しい具材だけ、メモで1回

アプリの画面を作るとき、サーバーから欲しいのは画面に出す項目だけです。ところが REST API では、窓口(URL)ごとに返ってくる中身があらかじめ決まっています。セット弁当しか置いていないお店のようなものです。

GraphQL は、欲しい具材をメモに書いて1回で注文できるカスタム弁当屋です。図1で、画面に出したい項目にチェックを入れて「注文する」を押してください。REST と GraphQL を切り替えると、窓口に行く回数と食べない具材の量がまるで違います。

図1 — RESTは「多すぎる」と「足りない」を同時に起こす。GraphQLは、書いたものだけが返ってくる

REST の2つの困りごと

REST では /users/1 が「ユーザー弁当」、/users/1/posts が「投稿弁当」と、窓口ごとに中身が固定されています。名前とアイコンしか使わないのに、住所や誕生日まで入ってくる。これをオーバーフェッチ(取りすぎ)と言います。

逆に、ユーザー弁当には投稿が入っていないので、別の窓口にもう一度並ぶ必要があります。これがアンダーフェッチ(足りない)。1画面のために3往復、というのは珍しくありません。スマホの回線では、この往復の回数がそのまま表示の遅さになります。

GraphQL は「メモ」がそのまま答えの形になる

GraphQL の注文メモ(クエリ)は、欲しいデータの形そのものです。図1の右上に出ているように、user の中に name を書き、posts の中に title を書く。すると返ってくるJSONもまったく同じ入れ子の形になります。

窓口は 1つ(/graphql)だけ。どんな組み合わせでも1回の注文で済み、書かなかった具材は入ってきません。画面を作る側が、サーバーの改修を待たずに自分で欲しい形を決められるのが最大の利点です。

万能ではない

カスタム弁当は、お店の側が大変です。注文ごとに中身が違うので、「この弁当をまとめて作り置き」ができません。REST なら URL ごとにキャッシュできたものが、GraphQL では工夫が要ります。

また、重すぎる注文も受け付けてしまいます。「フォロワーのフォロワーのフォロワーの投稿を全部」と書けば、サーバーは律儀に作ろうとします。深さや量に上限を設けるなど、自由と引き換えの守りが必要です。画面の種類が多く、要求がころころ変わるアプリほど GraphQL が効き、単純な API なら REST で十分なことも多いのです。

用語ミニ辞書

GraphQL: 欲しいデータの形をクエリで書いて取り出すAPIの方式。窓口は1つ。
クエリ: GraphQLの注文メモ。欲しい項目を入れ子で並べる。
スキーマ: 注文できる項目と型の一覧。お店のメニュー表にあたる。
オーバーフェッチ: 使わないデータまで受け取ってしまうこと。
アンダーフェッチ: 1回では足りず、何度もリクエストが必要になること。

まとめ

REST は窓口ごとのセット弁当。中身が決まっているぶん分かりやすくキャッシュもしやすいが、取りすぎと足りないが同時に起きる。GraphQL は欲しい具材をメモで1回。書いた形のまま返ってくるが、お店の側の工夫が要る。図1でチェックを増やしたり減らしたりすると、2つの得意・不得意がそのまま見えます。