woocommerce-store-api

WooCommerce Store API

Store API は、Woo ブロック（カート、チェックアウト、ミニカート）や外部連携で使用される公開 REST API です。/wc/store/v1/* 配下にあり、従来の /wc/v3/* 管理者向け REST API とは異なる独自の規約に従います。

このスキルを使用する場面

• /wc/store/v1/ 配下に新しいルートを追加する場合。
• 既存のルートのレスポンス形式、ステータスコード、引数スキーマを変更する場合。
• フロントエンドが使用する新しいリソースのスキーマを設計する場合。
• ブロック（または iAPI ストア）を Store API エンドポイントに接続する場合。

このスキルは、woocommerce-backend-dev（PHP 全般の規約）および woocommerce-performance（キャッシュの事前読み込みパターン）を補完します。一般的な規約については、まずこれらをお読みください。このスキルでは、Store API 固有の判断を扱います。

トピック

• authentication.md — permission_callback のスタイル、AbstractCartRoute による nonce の適用、どの抽象クラスを拡張するか。
• rest-conventions.md — パス／本文／クエリの使い分け、コレクション・アイテム・アクションの各ルート、ステータスコード、冪等性。
• schema-design.md — 公開契約としてのスキーマ、フィールドの選定、レスポンス形式の整合性。
• variation-handling.md — サーバーを正とするバリエーションの調整。
• performance.md — Store API レスポンスでキャッシュの事前読み込みを適用する場所。基本パターンについては woocommerce-performance への相互リンクがあります。

主な原則

• スキーマは公開契約です。 スキーマで宣言した内容が、ルートから返される内容でなければなりません。スキーマの生成後にレスポンスへフィールドを追加しないでください。
• 適切な抽象クラスを選びます。 Cookie を介してユーザーごとの状態を変更するルートは、AbstractCartRoute（nonce を適用します）を拡張するか、同等の CSRF 対策を実装する必要があります。AbstractRoute のみを使用するのは、読み取り専用または独自の認証を行うルートです。
• GET は安全です。 副作用も本文もありません。読み取り時の自動作成が許されるのは、メモリ上での実体化に限られます。永続化は、最初の明示的な書き込み時に行います。
• ID の判定はサーバーが行います。 バリエーションについて、クライアントから送られた属性ペイロードを信頼しないでください。バリエーション商品から属性を導出します。
• 使われないフィールドを提供しないでください。 将来にわたり値が一つしかないスキーマプロパティや、すでに別の場所で公開されているデータをそのまま反映するプロパティは、後から追加するより取り下げる方が難しい公開 API の一部です。

参考ファイル

• Authentication.php — Store API 全体に適用される認証フィルター。意図的に WordPress の Cookie nonce チェックを回避します。
• AbstractCartRoute.php — nonce の適用、カートセッションの読み込み、Nonce／Cart-Token レスポンスヘッダー。
• AbstractRoute.php — カートセッション／nonce の仕組みを必要としないルートの基底クラス。
• AbstractSchema.php — prepare_html_response()、prepare_money_response()、レスポンス形式の調整ヘルパー。
• CartItems.php — コレクション形式の POST／DELETE ルートの標準的な例。
• CartController.php — バリエーション調整の参考（parse_variation_data()）。