OCAPI HTTP メソッド 23.1

RESTful Web API の主な特徴は、RFC 2616 で定義されているように、HTTP メソッドを明示的に使用することです。Open Commerce API では、次のセクションで説明するように、これらのメソッドがサポートされています。

GET メソッドはサーバーのリソースを取得します。GET メソッドは安全なメソッド です。つまり、このメソッドによって、サーバーの状態が変更されたり、副作用が引き起こされたりすることはありません。このため、GET リクエストによってサーバーでトランザクションが開始されることはありません。

典型的な GET リクエストと、そのレスポンスは次のようになります:

このサンプルは、Identifier "123" を使用して Product リソースを取得するという、典型的な GET リクエストを表しています。レスポンスには、HTTP ステータスコード 200 が含まれています。このコードは、リソースが見つかり、見つかったリソースはレスポンスボディに含まれていることを示します。レスポンスには、"application/json" と文字セット定義 ("UTF-8") に設定されている "Content-Type" ヘッダーが含まれています。")

DELETE メソッドはサーバーの 1 つまたは複数のリソースを削除します。DELETE はべき等 なメソッドです。つまり、リクエストを何回行っても、1 回リクエストを行った場合と同じように、サーバーの状態が同じ結果になることを意味します。サーバーは、リソースがすでに削除されている場合は HTTP ステータスコード 204 (NO CONTENT) を、リソースが (もう現在は) 存在しない場合は 404 (NOT FOUND) を返します。

次の例は、URL の Identifier によってアドレス指定されているリソースの削除方法を示します:

このリクエストは、HTTP メソッドが変わったという点を除いて、前述の GET リクエストと似ています。レスポンスステータスコードは 204 で、サーバーがリクエストを正常に処理したが、返されたコンテンツはないことを意味します。

PUT メソッドは、リソースの作成、更新、あるいは置換に使用されます。これもまた、べき等 なメソッドです。リソースが作成された場合、このメソッドは、作成されたリソースをポイントする Location ヘッダーとともに 201 ステータスコードを返します。それ以外の場合は、200 ステータスコードを返します。

セキュリティ上の理由により、Production (本番) および Staging (ステージング) のインスタンスに対して HTTP PUT メソッドを使用して直接呼び出しを行うことは禁止されています。代わりに、HTTP メソッドの上書きで説明されている回避方法を使用して、POST メソッドを介して論理的な PUT 呼び出しを行います。Development (開発) および Sandbox (サンドボックス) のインスタンスで PUT 呼び出しを行う場合、Staging (ステージング) または Production (本番) の同じコードを使用することはできません。

PUT を使用すると、URL で指定した識別子でリソースを作成することができます。一方 POST は、サーバーによって識別子が提供される場合に使用します。

リソースが存在すると、PUT がリソースを "クリーンアップ" し、次にリクエストドキュメントに指定されたすべてのプロパティを適用します。PATCH とは異なり、PUT はリクエストドキュメントの一部でないプロパティにも影響を及ぼし、クリーンアップします。PUT 置換ロジックはリソース自体のみに影響し、他のリソースとの関係には影響を与えません。

次の例は、PUT メソッドを使用して買い物カゴの請求先住所を設定する方法を示しています：

PATCH メソッドでは、差分ドキュメントを送信することで部分的なリソースを変更できます。このメソッドは、安全あるいは_べき等のどちらでもありません。_PATCH ドキュメントには、新しいバージョンを生成するためのサーバーリソースの変更方法が記述されています。これに対し、PUT リクエストは既存ドキュメントを完全に置換します。

Open Commerce API は、部分的な更新を行う目的で PATCH メソッドを使用します。次の表で、作成と更新の動作について、PUT と PATCH を比較します:

メソッド	リソースが存在しない	リソースが存在する
PUT	リソースを作成します。	リソースを完全に置換することで更新します。UUID および関係は変更されません。リクエストで指定されなかったプロパティは失われます。
PATCH	リソースを作成しません。	部分的にリソースを更新します。サーバーは、リクエストで指定されたプロパティのみを更新し、その他のプロパティは変更されません。

次の例では、PATCH を使用して買い物カゴリソースを部分的に更新する方法を示します。サーバーは、差分ドキュメントのプロパティのみを更新し、その他のプロパティは変更されません:

POST メソッドは、(リクエストがサーバーの状態に影響する場合があるため) 安全あるいは (複数のリクエストが別々の結果を返す可能性があるため) べき等 のどちらでもありません。

Open Commerce API は、次の 3 つの目的に対してのみ POST を使用します。

リソースを作成します。PUT とは異なり、リソース識別子はサーバーによって提供されます。
HTTP メソッドの上書き。HTTP メソッドの上書きを参照してください。
RESTful リクエストへのマッピングが困難な特殊なアクション (パスワードのリセットのリクエストなど) の実行。

HEAD メソッドは GET メソッドに似ていますが、コンテンツ (ボディ) ではなくヘッダーのみを返します。ヘッダーは、GET リクエストのヘッダーと同じです。HEAD メソッドは安全なメソッド です。このメソッドによって、サーバの状態は変更されません。

OPTIONS メソッドは、指定された URL でサポートされている HTTP メソッドを Allow ヘッダーにリストします。このメソッドはキャッシュ可能ではなく、コンテンツを返しません。OPTIONS メソッドも安全なメソッドです。つまり、このメソッドによって、サーバーの状態が変更されることはありません。

AJAX フレームワークなどの一部の Web フレームワークでは、GET と POST の HTTP メソッドのみがサポートされています。Open Commerce API はこの制限を回避するために、HTTP メソッドを上書きできる POST リクエストをサポートしています。サポートされている上書きメソッドは、DELETE、HEAD、OPTIONS、PUT、および PATCH メソッドです。

これを実行するには、明示的な request/form パラメーター method を、上書きメソッドの大文字の値で指定します。次に、DELETE をシミュレーションする例を示します:

また、Commerce Cloud Digital HTTP ヘッダー x-dw-http-method-override を、上書きメソッドの大文字の値で指定することで、HTTP メソッドを上書きすることもできます。次に、DELETE をシミュレーションする例を示します:

リクエストパラメーターはヘッダーパラメーターよりも優先されます。

一部の PATCH、POST、および PUT の OCAPI では、リクエストボディが必要でない場合があります。これらの呼び出しのリクエストボディが空の場合、中間のプロキシで問題が発生する可能性があります (HTTP 500 レスポンスなど)。Content-Length リクエストヘッダーに値 '0' を指定していることを確認してください。