仕様として合意する項目
- 依頼する内容
- 操作の目的、必須と任意の項目、値の意味、入力を受け付ける条件。
- 実行できる範囲
- 誰が、どの対象に、どの操作を実行できるか。
- 返す内容
- 結果の項目、処理の状態、該当する情報がない場合の表現。
- 失敗の伝え方
- 入力の修正、再認証、時間を置いた再送など、呼び出し側が判断できる区別。
成功以外の応答も例にする
| 成功以外の応答も例にする | 区別すること | 呼び出し側が決める行動 |
|---|---|---|
| 条件に合う情報がない | 問い合わせは成立したが結果が空なのか、入力条件が不正なのか。 | 空の結果を示すか、条件の修正を求めるか。 |
| 実行する権限がない | 認証が必要なのか、認証済みでも操作が許されないのか。 | 再認証へ案内するか、権限の確認先を示すか。 |
| 依頼が重複した | 新しい処理を作ったのか、前の依頼と同じ結果を返したのか。 | 新しい結果を待つか、前の依頼の結果を確認するか。 |
| 応答を受け取れない | 未実行と判断できるか、相手側の処理状況が不明なのか。 | 再送するか、結果を問い合わせるか、担当者の確認を待つか。 |
変更が利用側に与える影響を見る
項目の追加、意味の変更、値の種類の追加は、それぞれ利用側の確認が必要です。変更前後の入力と応答の例を並べ、どの利用者や画面が影響を受けるかを確認します。
移行期間や古い呼び出しの扱いは、利用側の更新方法に合わせて合意します。仕様の版、変更点、確認が終わった利用先を残すと、切り替える条件を判断できます。
共通の例で取り決めを確かめる
- 代表的な例をそろえる
正常な入力、不足した入力、権限の違い、情報がない場合を、期待する応答と一組にします。
- 利用側と提供側で照合する
同じ例を使い、実際に送る内容、返る内容、画面や後続処理での扱いを照合します。
- 変更時にも再確認する
仕様を変えたときに確認する例を残し、影響を受ける利用先と切り替え条件を確認します。
まず、一つの呼び出しを具体化する
API を検討する際は、「何を依頼して、何を受け取ったら先へ進めるか」を一つ選びます。呼び出す画面やシステム、入力例、期待する結果、失敗したときの行動を並べるところから始められます。
外部サービスとの接続では、この取り決めに加えて、どちらの情報を基準にし、行き違いをどう照合するかも検討します。