API設計は、別のプログラムが機能やデータを利用するための約束を決める作業です。URLを並べるだけでなく、何を操作できるか、どの入力を受け付けるか、失敗をどう伝えるかを考えます。
ここではHTTPを使うWeb APIを対象に、設計の判断順を整理します。利用する側が内部実装を知らなくても、安全に呼び出し結果を扱えることを目標にしてください。
利用者が行う業務からリソースを決める
最初に「どの画面から、誰が、何のために呼ぶか」を書き出します。たとえば架空の申請システムなら、申請の登録、一覧確認、個別申請の参照が考えられます。
そのうえで、APIが扱う対象を整理します。Microsoftの設計資料は、REST APIをリソース中心に考え、内部データベースの表をそのまま公開しないことを勧めています。Web API設計のベストプラクティス
申請に複数の内部テーブルを使っていても、利用者が必要とする「一つの申請」の単位で返す設計を検討できます。どの項目を公開するかは、利用目的と権限から決めます。
操作とHTTPメソッドを対応させる
同じURLでも、参照と変更では意味が異なります。次は設計を考えるための仮例です。
| 利用側の目的 | 操作例 | 先に決めること |
|---|---|---|
| 一覧を見る | GET /requests | 絞り込み、並び順、ページ分割 |
| 一件を見る | GET /requests/{id} | 存在しないIDと閲覧権限の扱い |
| 新規登録する | POST /requests | 必須項目、登録結果、重複送信 |
| 一部を変更する | PATCH /requests/{id} | 変更可能項目、同時更新の扱い |
メソッドの意味はHTTPの仕様に従い、サービス固有の条件を追加で決めます。たとえば、登録を送った後に通信が切れた場合、利用側からは登録済みかどうか分からないことがあります。
このケースでは、単に「再送してください」とする前に、同じ処理を識別する方法と、結果を照会する方法を設計します。重複が許されない業務かどうかも要件です。
正常応答と失敗時の行動を一緒に設計する
正常時のJSONだけで合意すると、利用側が失敗時に判断できません。入力不足、対象なし、権限不足、一時的な障害などについて、応答コードと内容を整理します。
本記事では、失敗の種類ごとに次の情報をそろえることを勧めます。
- 利用側が表示する説明。
- 入力修正が必要か、時間を置くか、担当へ連絡するか。
- 自動再送してよい条件。
- 調査のために照合する識別子。
エラー本文に内部の接続情報や秘密を含める設計は避けます。利用側に必要な説明と、運用者が調査する詳細を分けてください。
応答サイズと変更時の影響を確認する
一覧APIでは、データが増えた後も扱えるかを考えます。全件を一度に返す前提にせず、必要な絞り込みやページ分割を検討します。Microsoftの資料にも、ページ分割、フィルタリング、版管理の設計が整理されています。
項目名や型を変えるときは、利用側がどう読むかを確認します。仮に文字列の状態値を数値へ変えるなら、既存の判定処理への影響を調べる必要があります。
変更案は、対象の利用者、移行期間、旧仕様の終了条件をまとめます。設計の選択理由はADRに残す方法もあります。
一つの業務シナリオで設計を確かめる
設計案ができたら、登録から確認までを利用側の立場でたどります。途中で失敗したとき、権限がないとき、同じ操作を繰り返したときも確認します。
まず一つの重要な操作について、入力・成功・失敗・再送・変更影響を説明できる状態にしてください。設計に関わる開発体制の相談は、システムエンジニアリングサービスをご確認いただけます。