DEV Community

Cover image for ヘッドレスコマースAPIとは？MACH、コンポーザブルコマース、契約レイヤー
Akira
Akira

Posted on • Originally published at apidog.com

ヘッドレスコマースAPIとは？MACH、コンポーザブルコマース、契約レイヤー

ヘッドレスコマースAPIは、コマースバックエンドが商品、カート、注文などの機能をストアフロントへ公開するための契約です。既製テーマに縛られず、Reactサイト、モバイルアプリ、POS、音声UIなどから同じコマース機能を呼び出せます。この記事では、ヘッドレスコマースAPIの設計ポイント、コンポーザブルコマースやMACHとの違い、そしてストアフロントチームやパートナーチームがAPI契約に依存する理由を実装目線で整理します。背景には、ソフトウェアがヘッドレス化し、APIが製品となるという考え方があります。

今すぐApidogを試す

コマースにおける「ヘッドレス」とは

従来のコマースプラットフォームでは、商品カタログ、カート、チェックアウト、HTMLページ、テーマが同じシステムに含まれます。テーマを選び、画面を調整し、同じプラットフォーム上で公開します。

ヘッドレスコマースでは、これを次の2層に分けます。

  • バックエンド: カタログ、価格、在庫、カート、注文ロジックを管理する
  • フロントエンド: ユーザーが触るストアフロントを自由に実装する

両者を接続するのがAPIです。

つまり「ヘッド」はプレゼンテーション層です。ヘッドレス化とは、固定された画面を取り外し、コマース機能をAPIとして公開することです。React、Next.js、ネイティブモバイルアプリ、スマートデバイス、音声アシスタントなど、複数のチャネルが同じバックエンドを利用できます。

実装上の分担は次のようになります。

[Web Storefront] ----\
[Mobile App] --------- API ---- [Commerce Backend]
[Partner App] -------/
Enter fullscreen mode Exit fullscreen mode

この分離により、フロントエンドチームはUIフレームワークやリリースサイクルを自由に選べます。一方、バックエンドチームは価格、在庫、注文ルールなどのコマースロジックを管理します。

ただし、柔軟性にはコストがあります。既製テーマのように「すぐ動くストア」は提供されません。ストアフロントの設計、実装、ホスティング、API連携、テストを自分たちで担う必要があります。

ヘッドレスを選ぶべき典型的なケースは次の通りです。

  • 既製テーマでは実現できないUXが必要
  • Web、モバイル、店舗端末など複数チャネルを同じバックエンドで運用したい
  • フロントエンドを独立して高速に改善したい
  • パートナーや外部サービスにコマース機能を公開したい

ヘッドレス vs コンポーザブル vs MACH

この3つは混同されがちですが、スコープが異なります。

用語 説明 スコープ
ヘッドレスコマース フロントエンドをコマースバックエンドから分離し、APIで接続する 1つのバックエンド、1つまたは複数のフロントエンド
コンポーザブルコマース カタログ、検索、決済、PIM、OMSなどを独立したサービスとして組み合わせる 複数のベストオブブリードサービス
MACH Microservices、API-first、Cloud-native SaaS、Headlessに基づくアーキテクチャ原則 製品ではなく設計思想

ヘッドレスは比較的狭い概念です。単一のモノリシックなバックエンドでも、ストアフロントがAPI経由で接続されていればヘッドレスと呼べます。

コンポーザブルコマースはさらに進みます。検索は専用サービス、決済は別ベンダー、PIMは独立システム、OMSも別サービスというように、機能ごとに最適なコンポーネントを組み合わせます。

MACHは、こうしたコンポーザブルな構成でよく採用される原則です。MACHアライアンスによると、MACHは次の4要素を指します。

  • Microservices
  • API-first
  • Cloud-native SaaS
  • Headless

重要なのはAPI-firstが中心にあることです。MACHではAPIは補助機能ではありません。各サービスが連携するための主要なインターフェースです。これは、APIを製品として扱うという考え方と同じ方向を向いています。

ヘッドレスコマースAPIが公開するもの

プラットフォームごとに仕様は異なりますが、ヘッドレスコマースAPIが扱う領域はおおむね共通しています。

  • カタログと製品

    • 商品一覧
    • 商品詳細
    • バリアント
    • コレクション
    • 画像や動画などのメディア

  • 検索とブラウズ

    • キーワード検索
    • フィルター
    • ソート
    • ページネーション

  • カートとチェックアウト

    • カート作成
    • 商品追加・削除
    • 数量変更
    • 割引適用
    • 配送先設定
    • 支払いへの遷移

  • 顧客

    • サインイン
    • アカウント管理
    • 住所管理
    • 注文履歴

  • 在庫と価格

    • 在庫数
    • 販売可否
    • 通貨別価格
    • 顧客グループ別価格

多くのプラットフォームでは、APIを次のように分けます。

Storefront API
  - 顧客向け
  - 読み取り中心
  - 商品表示、カート操作、チェックアウト

Admin API
  - 管理者・業務向け
  - 書き込みを含む
  - カタログ編集、注文管理、設定変更
Enter fullscreen mode Exit fullscreen mode

実装時は、まずどのAPIをどのクライアントから呼ぶのかを明確にします。特にAdmin APIをフロントエンドから直接呼ばないように、認証・認可の境界を設計する必要があります。

RESTとGraphQLの選び方

ヘッドレスコマースAPIではGraphQLがよく使われます。ストアフロントが必要なフィールドだけを1回のリクエストで取得しやすいためです。

例:

query ProductPage($handle: String!) {
  product(handle: $handle) {
    id
    title
    description
    images {
      url
      altText
    }
    variants {
      id
      title
      price {
        amount
        currencyCode
      }
      availableForSale
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

商品ページでは、タイトル、説明、画像、価格、在庫状態など、画面に必要なデータをまとめて取得できます。

一方、RESTも多くのプラットフォームで使われています。

GET /products/sku-123
GET /products/sku-123/variants
POST /cart
POST /cart/{cartId}/items
Enter fullscreen mode Exit fullscreen mode

RESTはHTTPメソッドやステータスコードと相性がよく、キャッシュや監視もしやすい構成にできます。

選定時は、プロトコルそのものよりも次を重視してください。

  • 契約が明確か
  • 変更管理ができるか
  • ドキュメントが保守されるか
  • テストしやすいか
  • フロントエンドが必要なデータを効率よく取得できるか

RESTとGraphQLの比較は、RESTとGraphQLも参考になります。

主なプラットフォーム

ヘッドレスコマースのプラットフォームは、大きくSaaS型とオープンソース型に分けられます。

  • commercetools

    • MACHアライアンスの創設メンバー
    • API-first、クラウドネイティブなコンポーザブルコマースプラットフォームとしてよく引用される

  • Shopify

    • Storefront APIでヘッドレス構築をサポート
    • ReactベースのフレームワークとしてHydrogenを提供
    • Shopify連携の出発点として、Shopify APIチュートリアルも利用できる

  • BigCommerce

  • Saleor

    • PythonとDjangoで構築されたオープンソースのGraphQLファーストなコマースエンジン

  • Medusa

    • Node.jsとTypeScriptで構築されたオープンソースのコマースエンジン
    • JavaScript/TypeScriptチームがバックエンド制御を重視する場合に選択肢になる

価格、ホスティング方式、APIの対応範囲は変わるため、採用前に各プラットフォームの最新ドキュメントを確認してください。共通するパターンは同じです。コマースエンジンはAPIで機能を公開し、チームはその上にストアフロントを構築します。

実装前に決めるべきAPI契約

ヘッドレス構成では、APIは単なる通信経路ではなく、チーム間の契約です。実装前に最低限、次を決めておくと手戻りを減らせます。

1. 商品レスポンスの形

商品ページが必要とするレスポンスを先に定義します。

{
  "id": "prod_123",
  "slug": "basic-t-shirt",
  "title": "Basic T-Shirt",
  "description": "Daily cotton t-shirt",
  "images": [
    {
      "url": "https://example.com/images/t-shirt.png",
      "alt": "Basic T-Shirt"
    }
  ],
  "variants": [
    {
      "id": "var_001",
      "sku": "TSHIRT-BLK-M",
      "title": "Black / M",
      "price": {
        "amount": "29.00",
        "currency": "USD"
      },
      "available": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

フロントエンドはこの形に依存します。後からフィールド名を変えると、Web、モバイル、パートナー連携が同時に壊れる可能性があります。

2. カート操作の状態遷移

カートAPIは状態を持つため、操作ごとの挙動を明確にします。

POST /carts
POST /carts/{cartId}/items
PATCH /carts/{cartId}/items/{itemId}
DELETE /carts/{cartId}/items/{itemId}
POST /carts/{cartId}/checkout
Enter fullscreen mode Exit fullscreen mode

決めるべき項目は次の通りです。

  • 在庫切れ商品の追加時にどう返すか
  • 価格変更が発生した場合にどう通知するか
  • 割引コードが無効な場合のエラー形式
  • チェックアウト前に再計算する項目
  • カートの有効期限

3. エラーレスポンスの形式

エラー形式がバラバラだと、フロントエンド側の実装が複雑になります。

例:

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "The selected variant is out of stock.",
    "details": {
      "variantId": "var_001"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

最低限、以下を統一します。

  • code
  • message
  • details
  • HTTPステータスコード
  • ユーザーに表示できるメッセージかどうか

4. バージョニング方針

破壊的変更は避けるべきです。どうしても必要な場合は、バージョニングと移行期間を用意します。

/v1/products/{id}
/v2/products/{id}
Enter fullscreen mode Exit fullscreen mode

またはヘッダーでバージョンを指定します。

Accept: application/vnd.example.commerce.v2+json
Enter fullscreen mode Exit fullscreen mode

基本方針は次の通りです。

  • フィールド追加は原則として安全
  • フィールド削除・型変更・名前変更は破壊的変更
  • 非推奨期間を明示する
  • パートナーや外部チームに事前通知する
  • CIで契約テストを実行する

チームがコマースAPI契約に依存する理由

ストアフロントがデカップリングされると、APIは全チームの合意点になります。

フロントエンドチームは、商品レスポンスの形が決まらなければ商品ページを実装できません。モバイルチームも同じ商品・カートAPIに依存します。ロイヤリティアプリ、税務サービス、マーケットプレイス連携、分析基盤などのパートナー統合も、同じ契約を参照します。

そのため、レスポンスの形を予告なく変更すると、複数のコンシューマーが同時に壊れます。

安定したAPI契約があると、各チームは独立して作業できます。

API Contract
  ├── Web Storefront Team
  ├── Mobile Team
  ├── Backend Team
  ├── Partner Integration Team
  └── QA / Automation
Enter fullscreen mode Exit fullscreen mode

逆に契約が曖昧だと、すべてのリリースが調整作業になります。

ヘッドレスコマースでは、契約を製品として扱うべきです。具体的には次を実施します。

  • OpenAPIまたはGraphQL Schemaで契約を管理する
  • サンプルレスポンスを用意する
  • モックサーバーでフロントエンド開発を先行させる
  • CIで契約テストを実行する
  • 破壊的変更を検出する
  • ドキュメントを常に最新にする

Apidogの役割

Apidogはコマースエンジン、CMS、決済ゲートウェイではありません。ストアを直接運営するものでもなく、導入するだけでヘッドレスやコンポーザブルになるわけでもありません。

Apidogが担うのは、API-firstな開発の中核になるレイヤーです。つまり、他のチームが依存するAPI契約を設計、テスト、モック、文書化する場所です。

ヘッドレスコマースでは、次のように使えます。

1. 先に契約を設計する

バックエンド実装の前に、ストアフロントAPIや管理APIをApidogでOpenAPI仕様としてモデル化します。

これにより、フロントエンドとバックエンドが事前に次を合意できます。

  • エンドポイント
  • リクエスト形式
  • レスポンス形式
  • エラー形式
  • 認証方式
  • サンプルデータ

2. バックエンド完成前にモックする

仕様からモックサーバーを立ち上げれば、コマースエンジンの実装が完了する前にストアフロント開発を進められます。

Frontend ---- Mock API ---- API Spec
Backend  ---- 実装中
Enter fullscreen mode Exit fullscreen mode

この進め方により、フロントエンドはリアルな商品レスポンスやカートレスポンスを前提にUIを実装できます。詳しくはモックAPI解説を参照してください。

3. CIで契約をテストする

API契約はリリースごとに検証する必要があります。Apidog CLIを使えば、GUIなしでAPIテストを実行し、CI/CDパイプラインに組み込めます。

Pull Request
  -> API tests
  -> Contract checks
  -> Deploy
Enter fullscreen mode Exit fullscreen mode

破壊的変更を本番反映前に検出できるため、ストアフロントやパートナー連携への影響を減らせます。

4. パートナー向けに文書化する

自動生成されたインタラクティブなAPIドキュメントは、ストアフロントチーム、モバイルチーム、外部パートナーの共通リファレンスになります。

特にパートナー連携では、次が重要です。

  • 認証方法
  • レート制限
  • サンプルリクエスト
  • サンプルレスポンス
  • エラーコード
  • 非推奨APIの扱い

APIが唯一のインターフェースになる理由については、ソフトウェアがヘッドレス化し、APIが製品となるも参考になります。ワークフローを試す場合は、Apidogをダウンロードして既存の仕様をインポートできます。

よくある質問

ヘッドレスコマースとコンポーザブルコマースは同じですか？

いいえ、異なります。ヘッドレスコマースは、APIを介してストアフロントをコマースバックエンドから分離する構成です。コンポーザブルコマースはさらに進み、カタログ、検索、決済、PIM、OMSなど複数の独立サービスを組み合わせて1つの体験を構築します。

すべてのコンポーザブルなスタックはヘッドレスですが、単一のバックエンドを使うヘッドレス構成が必ずしもコンポーザブルとは限りません。

ヘッドレスコマースAPIにはGraphQLが必要ですか？

必須ではありません。GraphQLは、ストアフロントが必要なフィールドだけを取得しやすいため、商品ページやカート画面と相性がよいです。ただし、多くのヘッドレスコマースAPIはRESTも使っていますし、両方を提供するプラットフォームもあります。

重要なのは、GraphQLかRESTかではなく、契約が安定していて、文書化され、テストできることです。

バックエンドが構築される前にヘッドレスコマースAPIをテストできますか？

はい、できます。API契約を仕様として定義すれば、リアルなレスポンスを返すモックサーバーを生成できます。

バックエンドの開発中でも、ストアフロントチームはモックAPIに対して画面実装とテストを進められます。その後、実際のAPIエンドポイントに切り替えます。

MACHアライアンスとは何ですか？

MACHアライアンスは、2020年に設立された業界団体です。Microservices、API-first、Cloud-native SaaS、Headlessの原則に基づくオープンなベストオブブリード技術スタックを推進しています。

commercetoolsのようなベンダーが創設メンバーです。MACHは購入する単一の製品ではなく、アーキテクチャ原則のセットです。

契約がストアである

ヘッドレスコマースでは、価値の中心がテーマからAPIへ移ります。ストアフロントが分離されると、コマースAPIはフロントエンド、モバイル、パートナー統合が実際に構築する基盤になります。

コンポーザブルコマースとMACHは、この考え方をさらに進めます。API-firstは追加機能ではなく、アーキテクチャの前提になります。

Apidogはコマースエンジンではありません。しかし、ヘッドレスコマースで重要になるAPI契約を設計、モック、テスト、文書化するためのレイヤーを提供します。ヘッドレスプロジェクトを進めるなら、Apidogで契約を先に固めるところから始めると、チーム間の並行開発を進めやすくなります。

Top comments (0)