注文サイトが新しい注文を業務システムに送信したとします。業務システムには保存されましたが、確認応答がサイトに届きません。サイトは再送するべきでしょうか。二重注文になる可能性はないでしょうか。この例は、API契約が業務運用で重要になる理由を示しています。API契約は両側に期待される動作を定め、成功するデモだけでは見えないケースも扱います。
このページの内容
業務の流れとデータの管理責任から始める
利用者の操作から結果の確定まで、一つのやり取りを整理します。注文の例では、注文番号をどちらが発行し、どのシステムが受注を判断し、顧客がどこで状況を確認するかを特定します。リクエストの受信と注文の受け付けは、別の出来事である可能性があるため区別してください。また、各情報をどのシステムが変更できるかも決めます。双方が配送先住所を編集できるなら、最新の画面に表示された値を正と決めつけず、更新を扱うルールを契約に含める必要があります。
- 注文、顧客、ステータス情報の管理主体を明記します。
- 利用者が直ちに確認すべき結果を定めます。
- 受信側のシステムが後から送る必要のある更新を特定します。
フィールドの定義を具体的にする
各メッセージについて、必須情報、許容値、情報がない場合の意味を文書化します。金額には通貨と明確な解釈が必要であり、タイムスタンプには合意したタイムゾーンのルールが必要です。現実的なサンプル注文を一つ使って、これらのルールを検討してください。「キャンセル済み」は注文全体なのか一品目なのか、空の住所は不明なのか意図的な削除なのかを確認します。呼び出し元ごとに、どのレコードを参照・変更できるかも記述します。こうした判断は仕様とアプリケーションの利用体験の両方に関わり、フィールド名を一致させるだけでは解決しません。
再送時の動作と役立つエラーを定める
注文の例では、次のようなルールを提案できます。合意した保持期間内に、同じリクエスト識別子と同じ注文内容が再送された場合は、既存の注文番号を返す。同じ識別子に異なる内容が使われた場合は、呼び出し元が解決すべき競合として扱う。識別子の適用範囲と保持期間は明示してください。そのうえで、訂正が必要な誤りと一時的な障害を分けます。タイムアウトだけでは注文が保存されたかどうかは分からないため、呼び出し元が次の対応を決める前に結果を確認できる手段が必要です。
- 配送先住所がない場合：フィールド単位の説明を返し、訂正してから再送します。
- 結果が不明な場合：リクエスト識別子を検索し、記録された状態と照合します。
- 一時的なサービス障害の場合：合意した再試行ポリシーに従い、試行のたびに新しい注文識別情報を作らないようにします。
契約のテストと変更方法を合意する
正常な注文、リクエストの再送、無効な住所、確認応答の中断を、両チームで順に検討します。どのケースでも同じ結果を想定しているか確認してください。これらの例は仕様と一緒に保管し、連携を変更する際にも使います。変更の承認、接続先チームへの連絡、障害調査の担当者を決めてください。引き継ぎでは、不要な顧客情報をさらさずにサポート担当者がリクエストを追跡する方法と、互換性のない変更を既存のAPI利用側へ導入する方法を説明する必要があります。