ヘッドレスWordPressのAPI設計：RESTとGraphQLの性能差と選択基準

標準のREST APIを使うのか、WPGraphQLを導入するのか。どちらもWordPressをヘッドレスCMSとして利用できる。にもかかわらず、データ取得の形、キャッシュの組み立て方、プラグインとの付き合い方、障害時の切り分け方はかなり違う。

ここを雰囲気で決めると、開発初期は順調でも、投稿一覧にカテゴリーやアイキャッチ画像、カスタムフィールドが増えたあたりでAPI設計のツケが回ってくる。取得回数が増え、必要のないデータまで運び、キャッシュが効かず、最後は「とりあえず全部返してフロントで捨てる」という、あまり誇れない構成に落ち着く。ヘッドレス化には、そういう罠がある。

この記事では、ヘッドレスWordPressにおけるREST APIとWPGraphQLを、性能だけでなく、導入コスト、保守性、キャッシュ、プラグイン互換性まで含めて比較する。

REST APIは標準装備だからこそ、最初の選択肢になりやすい

WordPress REST APIは、WordPress本体に標準で組み込まれている。追加プラグインを入れなくても利用でき、投稿や固定ページ、カテゴリー、タグなど、WordPressの基本的なリソースへアクセスできる。

代表的なエンドポイントは、投稿を取得する GET /wp/v2/posts だ。固定ページなら GET /wp/v2/pages、カテゴリーなら GET /wp/v2/categories という具合に、リソースごとにエンドポイントが分かれている。

この構造は、WordPressのデータモデルをそのまま外部へ公開するには分かりやすい。WordPress本体との距離が近く、標準機能を使う範囲なら追加の仕組みを覚える必要も少ない。個人開発や小規模なサイトで、まず記事一覧と詳細ページを取得したい程度なら、REST APIは十分に現実的な選択肢だ。

しかも、標準機能であることは運用上かなり大きい。プラグインを一つ追加するだけでも、更新、脆弱性対応、バージョン互換性、管理画面上の設定項目が増える。WordPressでは「一つくらい増えても同じ」と考えがちだが、その一つがAPIの中心になると話は変わる。

REST APIの基本的な強み

REST APIを選ぶ理由は、単に標準機能だからではない。ヘッドレスWordPressの構成では、次のような利点がある。

• WordPress本体だけで導入でき、専用プラグインへの依存を増やさずに済む
• リソース単位でエンドポイントが分かれているため、HTTPキャッシュの設計を始めやすい
• WordPressの標準投稿、固定ページ、カテゴリーなどとの対応関係が直感的
• REST APIを利用するクライアントや実装例が多く、トラブル時に調査しやすい
• カスタム投稿タイプや独自のRESTエンドポイントを追加する拡張方針を取りやすい

特に、フロントエンドがそれほど複雑でない場合は、REST APIの分かりやすさがそのまま開発速度になる。記事詳細ページを表示するために投稿を取得し、関連するカテゴリーや画像を必要に応じて取得する。サイトの規模が小さいうちは、この程度の分割でも大きな問題にならない。

ただし、REST APIには構造上の弱点もある。データが増え、1ページに必要な関連情報が増えるほど、リクエストの組み立てが面倒になっていく。

REST APIの弱点は、リクエスト数とオーバーフェッチに出る

REST APIでは、エンドポイントごとに取得する対象が決まっている。投稿一覧を取得して、その投稿に紐づくカテゴリー、著者、アイキャッチ画像、カスタムフィールドを取得する場合、それぞれのデータが別リクエストになることがある。

WordPressの標準APIには、関連データをある程度まとめて取得するための仕組みもある。しかし、画面に必要なデータを完全に一度で取り出せるとは限らない。テーマやプラグインが追加したフィールド、独自の関連情報、複雑な絞り込み条件が絡むと、フロントエンド側で複数のAPIレスポンスを組み合わせる処理が必要になる。

ここで起きるのが、リクエストの増加だ。

たとえば、記事一覧に次の情報を表示するとする。

• 投稿タイトル
• 概要
• 公開日時
• アイキャッチ画像
• 著者名
• カテゴリー名
• カスタムフィールドで設定した短い説明
• 関連記事へのリンク

投稿本体だけで必要な情報が完結すればよいが、実際には著者、カテゴリー、メディア、カスタムフィールドなどが別のデータとして存在する。APIのレスポンスを受け取った後に、さらに関連リソースを取りにいく処理が増える。

もちろん、すべての投稿について逐一関連データを取得すれば、かなり厳しい構成になる。そこでまとめて取得したり、クエリパラメーターを工夫したり、サーバー側で独自の集約エンドポイントを作ったりする。力技だが、現場ではよくある対応だ。

しかし、その時点でREST APIの「分かりやすさ」は少しずつ失われている。APIの表面は標準RESTでも、裏側ではフロントエンド専用の集約ロジック、キャッシュ、例外処理が動く。結局のところ、必要なデータ構造に合わせて別のAPI層を作っているわけだ。

オーバーフェッチは通信量だけの問題ではない

REST APIでは、クライアントが必要とする情報よりも多くのフィールドが返されることがある。これがオーバーフェッチだ。

記事カードにタイトルとURLだけが必要なのに、本文、メタ情報、埋め込み情報、メディア関連のデータまで返れば、レスポンスは大きくなる。1件だけなら気にならなくても、一覧で数十件、あるいは100件単位のデータを取得すると差が出る。

オーバーフェッチは通信量を増やすだけではない。レスポンスの解析、キャッシュ容量、ログの見通し、フロントエンド側の型定義にも影響する。不要なデータが常に返されると、画面側の実装者は「このフィールドは本当に必要なのか」を判断しづらくなる。

REST APIにも、取得フィールドを絞り込む考え方はある。必要なものだけを返す設計は可能だ。ただし、関連リソースが複数に分かれている場合、フィールドを絞ってもリクエスト構造そのものは単純にならない。

REST APIは遅いのではなく、必要なデータを集める仕事がクライアント側へ流れやすい。その積み重ねが、後から効いてくる。

WPGraphQLは必要なデータをクエリで指定できる

WPGraphQLは、WordPressにインストールして利用するオープンソースの外部プラグインだ。導入すると、[WordPressに専用の /graphql](/articles/laravelnoapilian/) エンドポイントが追加される。

REST APIのように投稿、カテゴリー、メディアといったリソースごとのエンドポイントを呼び分けるのではなく、クライアントが必要なデータの形をクエリとして指定する。1回のリクエストで、投稿とカテゴリー、著者、アイキャッチ画像など、画面に必要なフィールドをまとめて取得できる。

GraphQLの利点として語られやすいのが、オーバーフェッチの抑制だ。クライアントがタイトル、URL、公開日時だけを指定すれば、その範囲に絞ったレスポンスを返せる。記事詳細ページなら本文やメタ情報を追加し、一覧ページなら概要や画像だけにする、といった使い分けもしやすい。

REST APIでは「投稿を取得した後、関連情報をどう取りにいくか」が設計課題になりやすい。一方、WPGraphQLでは「どのフィールドをスキーマとして公開するか」と「クエリをどこまで複雑に許可するか」が課題になる。

楽になった部分と、別の苦労が移動した部分がある。ここを見落とすと、GraphQLを導入したのにサーバー側の負荷だけが増えるという、別方向の罠に入る。

WPGraphQLのデータ取得が向いている構成

WPGraphQLの強みが出やすいのは、フロントエンドの画面構造が複雑なサイトだ。

たとえば、トップページに次のようなブロックが並んでいるとする。

• 最新記事
• 特集カテゴリーの記事
• 著者別のおすすめ記事
• 固定ページに設定したバナー
• 関連するカスタム投稿
• ナビゲーションメニュー
• SEO用のメタ情報

REST APIで同じ画面を作る場合、複数のリソースを組み合わせる必要がある。各リクエストの順番や並列処理、失敗時の扱い、ローディング状態、キャッシュ単位を考えなければならない。

WPGraphQLなら、画面に必要な形を一つのクエリにまとめられる。もちろん、クエリが書けることと、サーバーが効率よく処理できることは別問題だ。それでも、フロントエンドから見たデータ取得の契約はかなり明確になる。

また、型を重視したフロントエンド構成では、スキーマを基準にデータの形を扱える点も大きい。WordPress側でどの投稿タイプがあり、どのフィールドが公開されているかを整理しやすい。複数の画面で異なるデータを取得する場合も、APIレスポンスを画面ごとに組み立てるより、クエリ単位で管理しやすい。

ただし、GraphQLは魔法の高速化装置ではない

WPGraphQLを導入すれば、どんな構成でもREST APIより速くなる。そう言い切る記事は、だいたい後半の運用で苦労する。

GraphQLは必要なフィールドだけを取得できるため、ネットワーク上のデータ量を抑えやすい。しかし、クエリが複雑になれば、WordPress側で多くのデータを組み立てる必要がある。関連データを深く辿るクエリや、大量の投稿を対象にしたクエリでは、データベース負荷が問題になることもある。

GraphQLでは、1回のリクエストに複数の取得処理を詰め込める。それは便利な反面、1回のリクエストが軽いとは限らない。エンドポイントの数が減ったから処理も単純になった、とは限らないのである。

さらに、クライアントが自由にクエリを作れる構成では、想定外に重いクエリが発行される可能性もある。公開サイトであれば、認証やレート制御、クエリの深さ、キャッシュ方針まで含めて設計しなければならない。

100件の投稿取得テストから見る性能差

REST APIとWPGraphQLの性能差を考えるとき、よく参照されるのが100件の投稿データを取得するテストだ。

WPGraphQLの公式ドキュメントが示した比較事例では、REST APIで100件の投稿を取得した際のレスポンスサイズが335KB、所要時間が7.91秒だった。一方、WPGraphQLでは必要なフィールドに絞り込んだクエリを使うことで、レスポンスサイズを小さくし、ダウンロード効率を高めている。

この数字は、ヘッドレスWordPressのAPI選定を考えるうえで参考になる。ただし、すべての環境にそのまま適用できるベンチマークではない。サーバー性能、データベースの状態、投稿本文の長さ、インストールされているプラグイン、キャッシュの有無で結果は変わる。

ここで見るべきなのは、単純な速度ランキングではない。REST APIは、あらかじめ定義されたリソースを取得する仕組みだ。WPGraphQLは、必要なフィールドだけを指定して取得する仕組みだ。その設計差が、同じ100件の投稿でもレスポンスサイズや通信効率に影響する。

比較するときは「1リクエストの速さ」だけを見ない

APIの性能を比べる際、レスポンスが返るまでの時間だけを測ると、判断を誤りやすい。

見るべき対象は、少なくとも次のように分けたほうがよい。

• 画面表示に必要なAPIリクエストの総数
• 1回あたりのレスポンスサイズ
• キャッシュが効いた状態での応答
• キャッシュがない状態でのWordPress側の処理
• 投稿数や関連データが増えたときの負荷
• エラー発生時に再試行しやすい構成か
• フロントエンドでデータを組み合わせる処理量

REST APIの1リクエストが速くても、1ページに必要なリクエスト数が多ければ、最終的な表示時間は伸びる。逆に、GraphQLの1リクエストが多くの処理を含んでいても、キャッシュが適切に効けば全体として安定する場合がある。

もちろん、その逆もある。GraphQLのクエリが複雑になりすぎ、キャッシュキーが細かく分散し、毎回WordPressがデータを組み立てる構成なら、単一エンドポイントがボトルネックになる。

性能比較は、API単体ではなく、実際の画面単位で行うべきだ。

この表だけを見るとGraphQLが上位に見えるかもしれない。しかし、取得効率が高いことと、保守が軽いことは別の評価軸だ。そこを一列に並べてしまうと、導入後に「思ったより面倒だ」という話になる。

キャッシュ設計はAPI選びと同じくらい重要だ

ヘッドレスWordPressでは、APIを高速化するだけでなく、そもそもWordPressへ毎回問い合わせない設計が重要になる。

REST APIの場合、URLがリソースごとに分かれている。投稿一覧、カテゴリー一覧、個別投稿といった単位でキャッシュを設計しやすく、CDNやリバースプロキシとの相性も考えやすい。URLの構造が安定しているため、キャッシュの無効化条件も比較的整理しやすい。

たとえば、投稿を更新したら個別記事のキャッシュを削除し、カテゴリー一覧やトップページも必要に応じて再生成する。完全に単純ではないが、どのURLがどのデータに依存しているかを追いやすい。

WPGraphQLでも、ネットワーク層でのGETリクエストを利用したキャッシュは可能だ。GraphQLだからキャッシュできない、という話ではない。ただし、クエリの内容がキャッシュキーに影響するため、同じ画面を取得しているのにクエリの書き方が少し違うだけで別キャッシュになることがある。

また、クエリに変数を使う場合、URLやパラメーターの正規化も必要になる。GraphQLの取得処理を自由に書ける分、キャッシュ戦略も自由になり、結果として設計者の責任が増える。

キャッシュが難しいのはGraphQLそのもののせいではない

GraphQLのキャッシュが難しい理由は、単一エンドポイントに異なるデータ取得要求が集まるからだ。

REST APIでは、投稿一覧のURLとカテゴリー一覧のURLは別になる。GraphQLでは、同じ /graphql に対して、画面ごとに異なるクエリが送られる。レスポンスの内容は違うが、外から見ると同じエンドポイントに見える。

そのため、次のような設計が必要になる。

• クエリ本文や変数を含めてキャッシュキーを設計する
• 同じ画面で使うクエリの形式を統一する
• 更新された投稿に依存するクエリを特定する
• キャッシュの有効期限と再生成のタイミングを決める
• クエリが増えたときにキャッシュが細分化しすぎないようにする

これはGraphQLの欠点というより、柔軟性に対する代金だ。何でも一つの入口から取れる構成は便利だが、その入口の中で何が起きているかを管理しなければならない。

静的生成なら、APIの速度問題を別の形へ移せる

JAMstack構成や静的サイトジェネレーターを使う場合、ビルド時にWordPressからデータを取得し、生成済みのHTMLを配信する方法がある。この場合、ユーザーのアクセスごとにWordPressへ問い合わせる必要はない。

ただし、記事更新のたびに全ページを再生成するのか、対象ページだけを再生成するのか、プレビューをどうするのかという別の問題が出る。投稿数が少ないうちは全体ビルドでも対応できるが、記事数や関連ページが増えると、ビルド時間が運用上の負担になる。

GraphQLを使ったから静的生成が不要になるわけでもない。REST APIだから動的配信しかできないわけでもない。APIはデータを取得する入口であり、配信方式とは切り分けて考えたほうがよい。

導入と保守では、WPGraphQLのプラグイン依存が効いてくる

WPGraphQLは、WordPressをヘッドレスCMSとして利用するための有力な選択肢だ。ただし、WordPress本体に標準搭載されている機能ではない。外部プラグインをインストールし、更新し、サイト固有の構成との互換性を維持する必要がある。

この差は、開発開始時には小さく見える。プラグインを追加してエンドポイントが動けば、導入は終わったように感じる。しかし、実際の保守では次のような確認が必要になる。

• WordPress本体の更新後も正常に動作するか
• 利用中のテーマやプラグインがスキーマに正しく接続されるか
• カスタム投稿タイプやカスタムフィールドをどう公開するか
• 権限や非公開コンテンツをどう扱うか
• プラグイン更新でクエリ結果が変わらないか
• 本番と開発環境でスキーマに差が出ていないか

特に、サードパーティ製プラグインの完全な互換性は期待しないほうがよい。WordPressのプラグインが管理画面上で正常に動いていても、そのデータが自動的にGraphQLのスキーマへ公開されるとは限らない。追加の拡張や独自実装が必要になる場合がある。

カスタムフィールドは最初に設計を決める

ヘッドレスWordPressでは、カスタムフィールドの扱いがAPI選定を左右することが多い。

REST APIであれば、カスタムフィールドをどのようにレスポンスへ出すかをWordPress側で明示する必要がある。独自のRESTフィールドを追加する場合、PHPで登録処理を書くことになる。出力形式を設計できる反面、フィールドが増えるほどコードの管理対象も増える。

WPGraphQLでは、カスタムフィールドをスキーマ上のフィールドとして扱えるようにする設計が必要になる。フロントエンドから見ると型のあるデータとして扱いやすいが、WordPress側でフィールドの公開方針を決めなければならない。

どちらを使っても、カスタムフィールドを適当に増やせば運用が破綻する。フィールド名、型、必須か任意か、表示対象、更新頻度を整理せずに作ると、APIの種類に関係なく管理不能になる。

GraphQLを導入すると設計が不要になるわけではない。むしろ、曖昧なWordPressのデータ構造を、スキーマという形で正面から見せられる。

WordPressヘッドレス化のデメリットはAPI以外にもある

REST APIとWPGraphQLを比較していると、APIの性能に議論が集中しやすい。しかし、ヘッドレスWordPressのデメリットはそこだけではない。

WordPressを管理画面として利用し、表示部分を別のフロントエンドへ分離すると、WordPressが本来持っていた一体型CMSとしての便利さがいくつか失われる。

たとえば、テーマ側で自然に動いていた次の機能は、別途連携が必要になる。

• プレビュー表示
• ログイン中のユーザー向け表示
• 問い合わせフォーム
• 検索結果
• パンくずリスト
• SEOメタ情報
• サイトマップ
• リダイレクト
• 埋め込みコンテンツ
• 管理画面からの即時反映

WordPressの管理画面で記事を更新しても、フロントエンドが静的生成なら、すぐに画面へ反映されるとは限らない。ビルドや再検証の仕組みが必要になる。プレビューも、管理画面から別アプリケーションへ安全にデータを渡す設計が必要だ。

また、WordPress用のSEOプラグインを導入しただけで、ヘッドレス側のSEOが完成するわけでもない。メタ情報をAPIで取得し、フロントエンドのHTMLへ正しく出力し、サイトマップや構造化データを別途構成する必要がある。

ヘッドレス化は、表示速度やフロントエンドの自由度を得る代わりに、WordPressが一体で提供していた機能を自分で接続し直す作業でもある。

ヘッドレス化を選ぶ理由を先に決める

APIの比較から入ると、RESTかGraphQLかという技術論に引っ張られる。先に考えるべきなのは、なぜヘッドレスにするのかだ。

フロントエンドを自由に設計したいのか。複数の表示先へ同じコンテンツを配信したいのか。静的生成によってアクセス集中に備えたいのか。WordPressのテーマ構造を使わず、別の技術スタックでUIを作りたいのか。

目的によって、必要なAPIの機能は変わる。

単純なブログを一つのフロントエンドで表示するだけなら、REST APIで足りる可能性が高い。複数の投稿タイプと関連データを一つの画面で扱い、フロントエンド側のデータ取得を統一したいなら、WPGraphQLの価値が出やすい。

逆に、ヘッドレス化の目的が曖昧なまま、流行しているからという理由だけで導入すると、API選択以前に構成全体が重くなる。WordPressのテーマで十分だったサイトを分離し、API、ビルド、プレビュー、SEO、認証を一つずつ再構築することになるからだ。

実際のプロジェクトでは、混在も現実的な解になる

REST APIとWPGraphQLは、必ずどちらか一方だけを選ばなければならないわけではない。

公開コンテンツの取得にはWPGraphQLを使い、運用ツールや単純なデータ更新にはREST APIを使う。あるいは、最初はREST APIで構築し、画面が複雑になった段階でGraphQLを導入する。こうした段階的な構成も現実にはあり得る。

ただし、APIを混在させる場合は、同じデータを異なる形式で取得することになる。投稿の公開状態、日時、カスタムフィールドの扱い、エラー形式などがずれると、フロントエンドの実装が分かりにくくなる。

混在させるなら、役割を明確に分けたほうがよい。

• 公開ページの読み取りはWPGraphQL
• 管理系の操作や単純な取得はREST API
• 画像やメディアの扱いは既存の仕組みに合わせる
• APIごとの認証方式を統一する
• 同じデータを返す場合のフィールド名と意味を揃える

「とりあえず両方使えるようにする」は、後から誰も使い方を説明できなくなる構成の始まりだ。混在は柔軟だが、設計なしにやると柔軟ではなく散漫になる。

プロジェクト規模別に見る、現実的な選択基準

最後に、どのようなプロジェクトでどちらが向いているかを整理しておく。

REST APIを選びやすいケース

次のような条件なら、まずREST APIを検討してよい。

1. 投稿や固定ページ中心の比較的単純なサイト

記事一覧と詳細ページが中心で、関連データも限定的なら、REST APIの複数エンドポイントでも構成は複雑になりにくい。WordPress本体の機能をそのまま使えるため、追加プラグインを減らせる。

2. WordPress標準機能との距離を保ちたい場合

コア機能との互換性や、一般的なWordPressの知識を活かしたいなら、標準REST APIは扱いやすい。将来の担当者が変わっても、構成を説明しやすい。

3. キャッシュをURL単位で管理したい場合

リソース別のキャッシュ設計を採用しやすく、CDNやリバースプロキシとの接続も整理しやすい。キャッシュの無効化条件を明確にしたいサイトでは、この分かりやすさが効く。

4. プラグイン依存を増やしたくない場合

サイトの要件がREST APIで満たせるなら、WPGraphQLを追加する理由は薄い。依存関係は少ないほどよい、という単純だが強い原則がある。

WPGraphQLを選びやすいケース

一方、次のような構成ではWPGraphQLを選ぶ意味が大きい。

1. 一つの画面で複数のデータ種別を扱う場合

投稿、著者、カテゴリー、カスタム投稿、メディア、ナビゲーションなどを一つの画面で表示するなら、必要な形にまとめて取得できる利点が出る。

2. フロントエンドの画面数が多い場合

画面ごとに必要なデータが異なるサイトでは、クエリによって取得内容を定義できる。REST APIのレスポンスを画面側で加工する量を減らしやすい。

3. データ取得の型と契約を重視する場合

複数人でフロントエンドを開発する、あるいは長期運用を前提にするなら、スキーマを中心にデータ構造を管理できることが助けになる。

4. オーバーフェッチを抑えたい場合

大量のデータを取得する画面で、必要なフィールドだけを明示したいなら、GraphQLの設計が適している。100件の投稿取得テストで示されたように、レスポンスサイズの削減が効く場面もある。

ただし、WPGraphQLを採用するなら、スキーマ設計、クエリの複雑さ、キャッシュ、プラグイン互換性を最初から運用対象に含める必要がある。

結局のところ、性能差より要件との相性で決まる

「ヘッドレス wordpress graphql rest api 比較」で調べると、GraphQLのほうが効率的、REST APIのほうが簡単、といった整理に行き着きやすい。大筋では間違っていない。しかし、実際のプロジェクトで重要なのは、どちらが優れているかではなく、どの問題を引き受けるかだ。

REST APIは、標準機能としての安定感と、リソース単位の分かりやすさがある。その代わり、関連データが増えるとリクエストの組み立てやオーバーフェッチへの対応が必要になる。

WPGraphQLは、必要なデータを一つのクエリで取得しやすく、複雑なフロントエンドとの相性がよい。その代わり、外部プラグインへの依存、スキーマ設計、クエリ負荷、キャッシュ戦略を自分たちで管理しなければならない。

個人開発や小規模サイトなら、まずREST APIで要件を満たせるかを確認する。複数のリソースを組み合わせる画面が増え、フロントエンド側のデータ取得処理が膨らんできたら、WPGraphQLを検討する。その順番で十分だ。

最初から理想的なAPIを選び抜こうとすると、開発そのものが始まらない。反対に、何も決めずに作り始めると、後でキャッシュとデータ構造の整理に追われる。

運用で吸収できる複雑さはREST APIで吸収する。画面とデータの関係が増え、コードだけでは整理しにくくなった部分はGraphQLで構造化する。結局のところ、その現実的な線引きが、ヘッドレスWordPressのAPI設計では一番長持ちする。

Related reading: WordPressとヘッドレスCMSの分岐点：個人開発で選ぶべき設計と移行の実態.