バックエンドとしての Drupal:GraphQL、JSON:API、RESTful、そして API の選択に潜む高くつく誤り

あるとき、デカップルド Drupal の計画ミーティングの途中で、CTO が私にこう尋ねました。「で、どの API を使うべきなんだ?」

一瞬、部屋が静まり返りました。フロントエンドは GraphQL を望んでいました。バックエンドは JSON:API を望んでいました。ある連携ベンダーはすでに REST を前提にしていました。プロダクトオーナーは、モバイルアプリがウェブサイトのリリースを待たなくて済むようにしたいだけでした。

この小さな問いは、たいてい技術的な問いのように聞こえます。しかし違います。これはガバナンスの問い、予算の問い、そして時には開発者のパーカーをまとった採用の問いなのです。

Drupal はデカップルド製品のバックエンドとして非常に有能です。すでに構造化コンテンツ、ロール、権限、ワークフロー、リビジョン、翻訳、メディア処理、タクソノミー、そして成熟したモジュールエコシステムを備えています。厄介なのは、そのコンテンツをどうやって Drupal の外に出すかを決めることです。Drupal コアはネイティブに JSON:API をサポートし、GraphQL はコントリビュートモジュールを通じて利用でき、Drupal の RESTful Web Services モジュールはリソース形式のカスタムエンドポイントの選択肢として残っています。Drupal 自身のデカップルドのドキュメントは、この役割分担を率直に述べています。JSON:API はコアにあり、GraphQL はコントリビュート、そして Drupal は API を通じて外部フロントエンドにコンテンツを公開できる、と。

それでも、チームは今なお選択を誤ります。

モダンに聞こえるから GraphQL を選ぶ。誰もが使ってきたから REST を選ぶ。そこにあるから JSON:API を選ぶ。どれも戦略ではありません。

もっと辛口に言えばこうです。ほとんどの Drupal ベースのコンテンツプラットフォームでは、JSON:API がデフォルトの出発点であるべきです。GraphQL は勝ち取るものです。REST は、他の2つが広すぎる、あるいは前提が強すぎる場合のために取っておくべきです。

これは一部の人を苛立たせるでしょう。結構です。

退屈な勝者から始めよう:JSON:API

JSON:API は、最良の意味で退屈です。

Drupal のコア JSON:API モジュールは、Drupal のエンティティに対して JSON:API 仕様を実装します。サイトコンテンツの CRUD 操作を公開する、設定不要で前提の定まった方法を提供し、Drupal の Entity API、Field API、キャッシュ、認証、認可の各システムと結びついています。

この一文には、経営層が気にすべき部分が含まれています。コアモジュールです。

コアであることは重要です。コアであるということは、たいていベンダー由来の予期せぬ問題が少なく、保守計画が立てやすく、セキュリティ体制が明確で、「カスタム API 層を理解している唯一の請負業者が必要だ」というリスクが小さいことを意味します。Drupal の JSON:API ドキュメントによれば、このモジュールはエンティティタイプとバンドルを中心に API を公開し、フィルタリング、include、ページネーション、ソート、リビジョン、翻訳、GET、POST、PATCH、DELETE、ファイルアップロード、そしてイベントを通じたリソースのカスタマイズをサポートします。

実際の例を挙げましょう。記事、著者、トピック、ランディングページのティーザー、画像を持つメディア企業を想像してください。フロントエンドチームは Next.js で記事ページを必要としています。モバイルアプリは同じ記事本文、ヒーロー画像、著者名、関連トピックを必要としています。JSON:API は、バックエンドチームがゼロから API 言語を発明することなく、これらの Drupal エンティティを公開できます。関連リソースは include を通じて埋め込むことができ、コレクションはフィルタリングやページネーションが可能です。

ペイロードは美しいか? 時には。時には、長いランチのあとに委員会が設計したかのように見えます。

しかし、それこそが要点でもあります。JSON:API は仕様であって、開発者個人の好みではありません。公式の JSON:API サイトは、これを JSON で API を構築するための仕様であり、レスポンスの形をめぐる議論を減らし、汎用ツールの利用を助ける共有された取り決めを持つもの、と説明しています。そのメディアタイプは application/vnd.api+json で、バージョン 1.1 は 2022 年 9 月 30 日に確定しました。

ここには隠れたマネジメント上の利点があります。標準化されたレスポンス形式は、オンボーディングを属人的でなくします。新しいフロントエンド開発者は、入れ子になった data、attributes、relationships 構造を今なお呪うかもしれません。それで結構です。少なくとも彼らが呪っているのは、ドキュメント化されたものなのですから。

誰も触れたがらない落とし穴

JSON:API は Drupal のコンテンツモデルをかなり直接的に公開します。それは強みになり得ます。特に Drupal が編集上の信頼できる情報源である場合です。しかし、Drupal 内部の形をフロントエンドに漏らしすぎることにもなり得ます。

コンテンツモデルがきれいなら、JSON:API は効率的に感じられます。コンテンツモデルが古い妥協の博物館なら、JSON:API はその散らかりを可視化します。

私は、field_new_body_2021、field_mobile_summary、field_legacy_related、field_do_not_use といったフィールドを持つ「記事」コンテンツタイプを見たことがあります。JSON:API はそれを魔法のように優雅な製品 API に変えてはくれません。実際に持っているモデルをそのまま公開します。少し残酷かもしれません。しかし役に立ちます。

Drupal のドキュメントは境界も明確にしています。JSON:API はエンティティ指向の CRUD を扱いますが、ログイン、パスワードリセット、アカウント作成といったビジネスルールは JSON:API の仕事の外です。アプリケーションが「ベンダーを承認する」「更新見積もりを計算する」「請求を提出する」といったドメイン上のアクションを必要とするなら、モジュールが便利だからといってそれらをコンテンツエンティティのエンドポイントに無理やり押し込まないでください。

その道はすぐに醜くなります。

GraphQL が優雅に感じられるのは、痛みを移動させるから

GraphQL は魅力的です。フロントエンドは欲しいフィールドをまさに正確に要求します。レスポンスはクエリと同じ形をしています。型付きのスキーマを持っています。コンポーネントベースのフロントエンドのために設計されているように感じられます — 実際、率直に言えばそう設計されたからです。公式の GraphQL サイトは、GraphQL を、強く型付けされたスキーマを持つ API 向けのオープンソースのクエリ言語かつサーバーサイドのランタイムと説明し、クライアントが固定のサーバーレスポンスを受け取るのではなく、選択したフィールドを要求する様子を示しています。

フロントエンドチームにとって、それは本当の改善です。

コンポーネントで構成されたホームページを考えてみましょう。ヒーロー、注目記事、イベント、スポンサー枠、ナビゲーション、地域別アラート。REST では、フロントエンドは複数のエンドポイントを呼び出すかもしれません。JSON:API では、コレクションを要求して関連リソースを include できますが、構造は依然としてエンティティの関係に従います。GraphQL では、クエリを画面により近い形にできます。それは、チームが製品の画面を素早く出荷するときに重要になります。

Drupal の GraphQL モジュールは、開発者が Drupal 10 と 11 向けに GraphQL スキーマを作成して公開できるようにします。webonyx/graphql-php を中心に構築され、公式の GraphQL 仕様をサポートし、/graphql/explorer に GraphiQL を含み、スキーマ作業のためのデータプロデューサープラグインとカスタムコードを開発者に提供します。

その表現を注意深く読んでください。「作成して公開する」です。

現在の Drupal GraphQL モジュールは、あらゆる Drupal フィールドをきれいな API にそのまま映し出す魔法の鏡ではありません。Drupal.org によれば、古い 3.x 版は Drupal エンティティから自動的にスキーマを生成し、Drupal の詳細を API 経由で公開していましたが、4.x はスキーマ設計を開発者に委ねるため、Drupal の内部を隠すことができます。同じページには、4.x では開発者がスキーマをセットアップしてマッピングする必要があると書かれています。

それは脚注ではありません。それは請求書です。

GraphQL は、製品とコンテンツストレージの間にきれいな契約を与えることができます。しかし、その契約は誰かが設計しなければなりません。編集者がフィールドを追加したとき、デザインシステムが変わったとき、パーソナライゼーションが導入されたとき、法務が地域別の同意ロジックを求めたとき、モバイルチームがオフライン同期を必要としたとき、それを誰かが保守しなければなりません。

いや、それでは丁寧すぎます。誰かがそれを所有しなければなりません。所有権こそ、多くの GraphQL 提案に欠けている項目なのです。

GraphQL がコストに見合うとき

GraphQL は、API それ自体が一つの製品であるときに意味を持ちます。

数十のマイクロサイト、学生向けモバイルアプリ、デジタルサイネージ、教員プロフィール、コースカタログ、そしてデザインシステムを持つ大規模な大学は、GraphQL 層の恩恵を受けるかもしれません。消費者は多様です。コンテンツグラフは深いです。フロントエンドチームは選択的なアクセスを必要とします。組織は、Drupal バンドルの癖を隠す API 契約を望むかもしれません。

GraphQL は、Drupal が複数の情報源のうちの一つにすぎない場合にも適合します。コンテンツは Drupal から、価格は ERP から、在庫状況は予約エンジンから、ユーザーの権限は CRM から来るかもしれません。GraphQL は、リゾルバーが異なるシステムから取得する一方で、クライアントに一貫したスキーマを提示できます。GraphQL のモデルは、強く型付けされたスキーマとクライアントが指定するレスポンスの形を中心に構築されており、まさにそれが、この種のコンポジション層でうまく機能する理由です。

しかし、ヘッドレスのフロントエンドを持つ普通のマーケティングサイトについてはどうか? 私は懐疑的です。ちょっと苛立ちすら覚えます。

本当の必要が「React が Drupal から記事を読む」ことなら、GraphQL はコスプレパーティーかもしれません。JSON:API の include とフィルターを学ぶのを避けるために、アーキテクチャの費用を費やすことになります。さらに悪いことに、たった2人の開発者しか理解できない独自の API 層を作ってしまうかもしれません。

Drupal の GraphQL プロジェクトページによれば、安定版リリースは Drupal のセキュリティアドバイザリーポリシーの対象であり、Drupal 10 と 11 向けの最近のリリース(2026 年 4 月 29 日にリリースされた 8.x-4.14 や、Drupal 10.4 と 11 向けの 5.0.0 ベータを含む)が掲載されています。それは健全です。しかし設計作業をなくすものではありません。

コントリビュートモジュールは、成熟していても、なお誤ったデフォルトであり得ます。

RESTful Web Services:古く、便利で、たいてい使いすぎ

REST は、話し手が必要とする意味なら何でも指す言葉の一つになってしまいました。あるときはきれいなリソース指向の HTTP を意味します。あるときは「コントローラーから JSON を返す」を意味します。あるときは「ベンダーがエンドポイントと PDF をくれた」を意味します。

Roy Fielding の博士論文は、REST を分散ハイパーメディアシステムのためのアーキテクチャスタイルとして紹介し、クライアント・サーバーの分離、ステートレスな通信、キャッシュ、統一インターフェース、階層化システム、そしてオプションのコードオンデマンドといった制約を伴っていました。その本来の考え方は、プロジェクト計画で REST と呼ばれるものの多くよりも厳格です。

Drupal の RESTful Web Services モジュールが便利なのは、特定のメソッド、シリアライズ形式、認証を伴ってリソースを公開できるからです。Drupal の学習資料は、エンティティ向けの REST リソース、GET・POST・PATCH・DELETE といったメソッドのサポート、JSON または XML のシリアライズ、そして Basic 認証、Cookie、あるいは OAuth などの他モジュールを通じた認証について説明しています。また、安全でないメソッドには X-CSRF-Token リクエストヘッダーが必要であるとも記されています。

これは REST を、限定された連携作業に適したものにします。

決済プロバイダーが取引ステータスを Drupal に POST する。倉庫システムが更新された製品マニュアルの一覧を取得する。パートナーポータルが、承認済みアセット向けに慎重に形作られた1つのエンドポイントを必要とする。レガシーなモバイルアプリがすでに /api/v1/articles/{id} を期待していて、今四半期には書き換えられない。

REST は制御を与えてくれます。同時に、白紙症候群も与えます。

取り決めがすでに選ばれている JSON:API とは違い、カスタム REST エンドポイントには決定が必要です。URL の形、レスポンス形式、エラー形式、ページネーションの方式、フィルタリングの構文、バージョニング、認証、キャッシュヘッダー、ドキュメント、非推奨化ポリシー。OpenAPI はその面をドキュメント化するのに役立ちます。OpenAPI Specification は、人間とコンピューターがソースコードを読まずに HTTP API を理解できるよう記述する、標準的で言語非依存の方法です。

それでも、あなたは選択をしなければなりません。

そしてその選択は残り続けます。2週目に設計された雑なエンドポイントが、何年も製品につきまとうことがあります。世に出回っているあるアプリのバージョンが、いまだそれに依存しているからです。

問題は「どの API が最良か?」ではない

その問いの立て方は怠慢です。申し訳ないですが、そうなのです。

より良い問いはこうです。あなたの組織はどんな種類の結合を負担できるのか?

JSON:API は、消費者を Drupal のエンティティモデルに結合します。Drupal が主要なコンテンツシステムで、フロントエンドが差し替え可能なプレゼンテーション層である場合、それはしばしば許容できます。その見返りは、スピードとバックエンドでの発明の少なさです。

GraphQL は、消費者をあなたのチームが設計したスキーマに結合します。うまくやれば、そのスキーマは Drupal を隠し、製品ドメインを表現します。まずくやれば、コードで保守される第二の CMS モデルになります。

REST は、消費者をカスタムエンドポイントに結合します。特定の連携には優れていますが、広範なコンテンツ配信には危険です。すべてのエンドポイントが、それぞれ独自の保守の尾を引く小さな製品になるからです。

経営の運営委員会に提示するとしたら、こういう版になります。

表は少し無味乾燥ですが、これはミーティングを節約してくれます。

プロジェクトマネージャーが注視すべきこと

API の選択は、人々が認める以上にプロジェクト計画を変えます。

JSON:API では、クリティカルパスはコンテンツモデリングです。コンテンツモデルがよく考えられていれば、API 作業は素早く進みます。コンテンツモデルが混沌としていれば、フロントエンド開発は遅くなります。すべてのクエリが、また別の編集上の妥協を露呈させるからです。フロントエンドチームがページを配線し始める前に、フィールドの命名、再利用可能なパラグラフのパターン、メディアの関係、タクソノミー、権限にシニアの注意を向けてください。

GraphQL では、クリティカルパスはスキーマの所有です。誰がスキーマを設計するのか? 誰が破壊的変更をレビューするのか? 誰がリゾルバーを書くのか? バックエンドの読み込みを過剰に引き起こす入れ子クエリのようなパフォーマンス問題を、誰が扱うのか? Drupal の GraphQL モジュールは、データプロデューサープラグインや GraphiQL を含むツールと拡張ポイントを提供しますが、バックエンドエンジニアリングの規律の必要性をなくすわけではありません。

REST では、クリティカルパスは契約の規律です。すべてのエンドポイントに、ドキュメント、テスト、認証ルール、エラーの意味論、そしてバージョニングの物語が必要です。最初のエンドポイントを作るとき、REST は安く見えます。5つ目のエンドポイントが真実を語ります。

もう一つ。認証はしばしば過小評価されます。Drupal JSON:API は Drupal の認証・認可システムと結びついており、REST は Basic 認証や Cookie などの認証プロバイダーを使え、OAuth はコントリビュートモジュールを通じて加えられるのが一般的です。Lupus Decoupled Drupal のドキュメントは、デカップルド構成でトークンによって API リクエストを認証する方法として Simple OAuth を示しています。

それをローンチ前のスプリントに残さないでください。そのスプリントはすでに呪われています。

パフォーマンス:誰もが単純化する議論

GraphQL のファンは、それがオーバーフェッチを避けると言います。本当です。JSON:API のファンは、include が往復回数を減らすと言います。これも本当です。REST のファンは、HTTP キャッシュが単純だと言います。またしても本当です。

さて、不愉快な部分です。3つとも速くなり得るし、3つとも遅くなり得ます。

GraphQL はペイロードのサイズを減らせますが、リゾルバーが不注意だと、複雑な入れ子クエリがバックエンドを痛めつけます。JSON:API は Drupal のレスポンスキャッシュと include を使えますが、ペイロードが冗長になることがあります。REST は HTTP キャッシュにきれいに対応できますが、カスタムエンドポイントは、パフォーマンステストが始まるまでキャッシュ可能性を忘れがちです。Fielding の REST 制約にキャッシュが含まれるのは、キャッシュがネットワークトラフィックとレイテンシを減らせるからですが、古いデータとキャッシュの無効化は依然として現実のトレードオフです。Drupal の JSON:API ドキュメントはこのモジュールを Drupal のレスポンスキャッシュと明示的に結びつけており、GraphQL モジュールは Drupal.org 上で Decoupled、Developer tools、Performance に分類されています。

ですから、いいえ、GraphQL は自動的に「パフォーマンスの選択肢」ではありません。

最初のパフォーマンス改善は、たいていより良いコンテンツモデリングです。2つ目はキャッシュ戦略です。3つ目は、誰もデータアクセス層を書かなかったせいで同じエンドポイントを12回呼ぶような、愚かなクライアントの挙動を避けることです。

華やか? いいえ。効果的? はい。

率直な選定フレームワーク

もし私が創業者や CTO に助言するなら、この順序から始めます。

第一に、デカップルする理由がないなら、Drupal の通常のレンダリングされたページを使ってください。デカップリングは、ホスティング、プレビュー、ルーティング、キャッシュ、デプロイ、認証、デバッグの複雑さを加えます。Drupal 自身のデカップルドのドキュメントは、レイアウトがフロントエンドに移り、バックエンドが API を通じてコンテンツを公開すると述べることで、標準の Drupal とデカップルドの Drupal を区別しています。その移行はタダではありません。

第二に、主にモダンなフロントエンドのためにデカップルするなら、JSON:API から始めてください。デモではなく、本物のページを1つ作りましょう。メディア、メニューやナビゲーション、関連コンテンツ、プレビューの必要性、必要なら認証、そしてキャッシュの挙動を含めてください。6枚のアーキテクチャ図よりも、1枚の不格好なページから多くを学べます。

第三に、消費者体験がスキーマ作業を正当化するときにのみ GraphQL に移ってください。良い理由には、複数のフロントエンド消費者、Drupal の内部を隠す必要性、複雑なコンテンツグラフ、システム横断の集約が含まれます。悪い理由には、「うちのフロントエンド開発者が Apollo を好きだから」や「投資家向け資料に GraphQL と書いてあるから」が含まれます。

第四に、厳密な境界を必要とする連携には REST を使ってください。パートナー向けエクスポートのカスタムエンドポイントはきれいであり得ます。手作りのエンドポイントだらけのコンテンツプラットフォーム全体は、ラベルのない鍵でいっぱいの引き出しになりかねません。

そして Drupal のモデルを整理してください。お願いします。誰も所有していないコンテンツモデルを、いかなる API 層も完全には救えません。

「将来を見据えた(future-proof)」の政治学

経営層は「future-proof」という言葉を好みます。理由は分かります。バックエンドの再構築を承認し、18か月後に、選んだ API が会社を袋小路に追い込んだと聞かされたい人はいません。

しかし将来を見据えることは、たいてい最も派手な API を選ぶことよりも、変化がどこで起こることを許すかを選ぶことに関わります。

JSON:API はこう言います。「Drupal のモデルが契約だ」。それは正直で、速い。

GraphQL はこう言います。「私たちの製品スキーマが契約だ」。それは強力で、高くつく。

REST はこう言います。「このエンドポイントが契約だ」。それは正確で、そして容易に保守問題へと増殖する。

普遍的な勝者はいません。あるのは適合だけです。

私の偏りは単純です。製品を支えられる、最もカスタムでないものから始める。Drupal では、それはたいてい JSON:API を意味します。所有者と予算を名指しできるようになったら GraphQL を加える。連携が独自の入り口に値するほど具体的なら REST を加える。

最悪の選択は、流行のために行われる選択です。流行は保守には決して現れないのですから。

市場で第1位の Drupal 開発会社をお探しですか? たった今、見つかりました。

私たちは、妥協なく、速く、安全で、スケーラブルなプラットフォームを提供するために作られた、最高の Drupal 特化型デジタルエージェンシーです。新規構築やリデザインから、移行や長期サポートまで、私たちの Drupal エキスパートが、ブティック水準のきめ細やかさでエンタープライズ級の成果を届けます。

今日、ぜひご相談ください。あなたの Drupal ロードマップを、高いパフォーマンスの現実に変えましょう。