API のベスト・プラクティス

ベスト・プラクティスの推奨事項は、 IBM のお客様、サービス担当員、および品質保証テスターの経験に基づいています。これらのベスト・プラクティスの目的は、ソフトウェアの使用時に発生した懸念事項に関する一般的なガイダンスを提供することです。

API 呼び出しを行うには、有効なアクセス・トークンを使用する必要があります。通常、トークンは 12 時間有効です。トークンを一度生成し、トークンをキャッシュすることで再利用する。例として、トークンをクライアント側のメモリに保存し、同じクライアントから行われる後続のすべての呼び出しに再利用することができます。トークンの生成について詳しくは、 API へのアクセスと認証を参照してください。
トークンが欠落しているか無効なトークンを指定して API が呼び出されると、認証エラーが応答で受信されます。認証エラーを処理するためのベスト・プラクティスとして、トークン生成要求を発行してトークン・キャッシュをリフレッシュしてください。その後、更新したトークンで Sterling Intelligent Promising API を呼び出して再試行する。
有効期限が切れる前 (例えば 11 時間ごと)、または 401 無許可応答が発生したときに、トークンを自動的に再生成するメソッドを実装します。
リクエストごとの最大ペイロードサイズが500KBを超えないようにする。この制限は、安定性を維持し、故障を避けるために設定されている。
最良のパフォーマンスを得るには、各 API 呼び出しをアイテム-ノードまたはアイテム-ネットワークの組み合わせ 100 個までに制限してください。次に、追加の組み合わせを複数のAPIコールに分ける。
API ドキュメントにのみ記載されている HTTP ヘッダーを渡す。詳細は APIドキュメントを参照。

可用性 API

ウェブサイト上の商品詳細ページやリストページでは、該当するアイテムの「Get Node Availability Product by Date API 」(/availability/{itemId}/node)または「 Get Network Availability Product by Date API」 (/availability/{itemId}/network)を使用します。
カートまたは注文の場合は、 Get Node Availability API (/availability/node) または Get Network Availability API (/availability/network) を、カートまたは注文のアイテムとともに使用します。
カートのチェックアウトには、予約API (/reservations) を使用して、売り過ぎを防ぎます。
V2 の可用性APIでは、 requestedEndTs の日付形式を使用する。例えば、 "2020-03-02Z"。
2020-03-02T15:43:18.279Z のように、日付の代わりにタイムスタンプが使用された場合、APIは不正なリクエスト例外を発行する。
注： requestedEndTs の日付フォーマットの検証は、7月末のリリースから適用されます。

分配グループ API

APIはPUTメソッドのみをサポートしているUpdate Distribution Group PUT 要求はべき等であるため、既存の分配グループを更新するとグループ全体が置き換えられます。
- 既存の分配グループに新しい出荷ノードを追加する場合は、ペイロードに既存の出荷ノードも含まれていることを確認してください。
- 既存の分配グループから出荷ノードを削除する場合は、グループに保持する出荷ノードのみがペイロードに含まれていることを確認してください。
この API は、出荷ノードがグループに追加されたとき、またはグループから削除されたときに、分配グループの可用性を自動的に同期します。
前の同期が完了するまで、同じ配布グループに対して後続の同期をトリガーしません。分配グループの同期は、インスタント・プロセスではありません。また、送信する要求の数を減らすことをお勧めします。例えば、分配グループから 3 つのノードを削除する場合は、3 つのノードをすべて削除して 1 つの要求を送信します。
GET Job API を使用して同期状況を取得できます。 Distribution Group APIが呼び出されると、GET Job API URLがAPIの出力に表示されます。例:
```
{
    "job": {
        "href": "http://api.watsoncommerce.ibm.com/inventory/us-abcdabcd/v1/jobs/a2f173e7-2023-4e3d-b21d-2b6801f61d1b"
    }
}
```
次の例に示すように、GET Job API をURL で呼び出すことで、指定した求人の状態を取得することができます。
```
{
    "id": "a2f173e7-2023-4e3d-b21d-2b6801f61d1b",
    "status": "completed",
    "triggeredTs": "2021-02-22T19:59:12.585Z",
    "startedTs": "2021-02-22T19:59:12.849Z",
    "completedTs": "2021-02-22T19:59:13.155Z",
    "data": {
        "distributionGroupId": "USEast",
        "diffNodes": [
            "USEast-Node1",
            "USEast-Node2"
        ],
        "sourceTs": "2021-02-22T19:59:12.565Z"
    }
}
```
出力の status フィールドを確認します。

完了

ジョブが正常に終了しました。この場合、次の要求を送信できます。

開始済み

ジョブは進行中です。この場合、同じ分配グループに対して別の同期をトリガーしないでください。ただし、別の分配グループに対して同期をトリガーすることはできます。

トリガーされた

ジョブはまだ開始されていません。この場合、同じ分配グループに対して別の同期をトリガーしないでください。ただし、別の分配グループに対して同期をトリガーすることはできます。

API が状況コード 404 を返した場合は、要求を安全に再実行依頼できます。