規約

最終更新: 2026年6月22日

WEEGLOO API をコードから呼び出すとき、すべてのリクエスト・レスポンスに共通して適用される HTTP 規約をここにまとめます。レスポンスのメディアタイプ、部分更新（JSON Patch）、同時更新の競合を防ぐ X-Weegloo-Version ヘッダーがこれに該当します。個々のリソースのエンドポイントは各リソースのリファレンスで扱い、それらのエンドポイントが共通して従う規約はこのページを参照します。

レスポンスのメディアタイプ

WEEGLOO API のレスポンスは application/vnd.com.weegloo.v1+json;charset=UTF-8 メディアタイプを使います。通常の application/json ではありません。

リクエストに Accept: application/json を送らないでください。この値でメディアタイプをネゴシエートすると WEEGLOO のベンダータイプと一致せず、406 Not Acceptable のような失敗が発生することがあります。

  • 推奨: リクエストで Accept ヘッダーを省略します（例: fetch に Accept を含めない）。
  • どうしても送る必要がある場合は、レスポンスと同じベンダータイプ application/vnd.com.weegloo.v1+json;charset=UTF-8 をそのまま使います。

axios インスタンスや共通の fetch ラッパーを作るとき、デフォルト値が Accept: application/json を強制しないようにします。（このルールはアプリケーションコードに適用されます。AI エージェントは HTTP を直接呼び出さず MCP ツールを使います。）

部分更新 (JSON Patch)

Content・Media・Content Type など、ほとんどのリソースは PATCH で一部だけ選んで更新できます。本文は RFC 6902 JSON Patch 形式の配列です。各項目は操作 op、対象の位置を指す JSON Pointer のパス path、そして操作に応じて value または from を持ちます。

PATCH リクエストの Content-Type ヘッダーは application/json-patch+json でなければなりません。通常の application/json ではありません。

次は 1 つの Field の値だけを変更する例です。

[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]

本文全体で置き換えるには PUT を使います。PUT はリソースの本文全体（またはエンドポイントの契約が許す場合は、変更する部分だけを含む部分本文）で置き換えます。どのエンドポイントが PATCH をサポートするか、PUT が全体置換か部分置換かは、各リソースページのエンドポイントブロックで確認してください。

同時実行制御 (X-Weegloo-Version)

同じリソースを 2 か所で同時に変更すると、一方の変更がもう一方を上書きすることがあります。WEEGLOO はこれを防ぐために楽観的同時実行制御を使います。リソースを更新・削除・状態遷移するとき、リクエストに現在の sys.version を X-Weegloo-Version ヘッダーに乗せて送ります。

サーバーはこの値が保存されている現在のバージョンと一致するときだけ変更を受け入れます。ヘッダーが欠けていたり値が食い違ったりすると（その間に誰かが先に変更してバージョンが上がった場合など）、競合エラー WGL409005 で拒否されます。このときはリソースを再取得して最新の sys.version を受け取ったうえで変更を再試行します。エラーレスポンスの形式は エラー で扱います。

どのリクエストに必要かは次のとおりです。

区分X-Weegloo-Version
更新(PUT)・部分更新(PATCH)必要
状態遷移（公開・公開停止・アーカイブ・アーカイブ解除）必要
作成(POST)なし
削除(DELETE)一部のみ必要

version を持たないリソース（ServiceUser）はこのヘッダーを受け取りません。正確にどのエンドポイントがこのヘッダーを要求するかは、各リソースページのエンドポイントブロックにある requestHeaderSchema を確認してください。sys.version 自体の意味は システム属性 (sys) で扱います。