AIにAPI endpointを列挙させる前に、利用者が行う操作と、システムが管理するresourceを整理します。画面ごとにURLを増やすと責務が重複しやすく、必要なdataや失敗時の約束も曖昧になります。設計の出発点は「誰が何をしたいか」であり、API形式をRESTにするかRPC等にするかは既存systemと要件を見て決めます。
目次
endpoint一覧より先に利用者の操作を記録する
各操作について、actor、目的、対象、前提条件、成功時の結果、失敗時の扱いを書きます。「注文を作る」なら、誰が、どの顧客のために、どの品目を、どの状態から登録するのかが要ります。認証済みというだけで操作権限があるとは限らないため、resource単位のauthorization条件も別にします。閲覧、作成、更新、取消、検索が同じ権限でよいと決めつけないでください。
その後、業務上識別して管理するものをresource候補にします。画面名や動詞からそのままpathを作るのではなく、注文、顧客、コメントのような概念が永続化・参照される単位かを確認します。一時処理や集計、複数resourceを伴う操作は、単純なCRUDに押し込めず、既存のAPI styleと整合するoperationとして別に記述します。RESTが適切かは要件依存であり、標準的な正解として固定しません。
method / path / 意味を一緒に決める
OpenAPI SpecificationではpathsにPath Itemを置き、HTTP methodごとにoperationを記述します。設計表ではpathだけでなく、目的、対象resource、認証・認可、request、response、error、冪等性を同じ行に並べます。一覧と個別取得を分ける場合も、pagination、filter、sort、empty resultの意味を定義します。利用者が必要な情報を一度に得られるかと、不要な情報まで過剰に返さないかの両方を見ます。
表は横にスクロールできます
| actor / action | resource | operation案 | 成功時 | 代表的な失敗 |
|---|---|---|---|---|
| 担当者が注文を見る | order | GET /orders/ | 許可された注文の概要 | 404または権限方針に沿う応答 |
| 利用者が注文を作る | order | POST /orders | 作成結果と識別子 | validation / conflict |
| 担当者が状態を変える | order | PATCH /orders/ | 更新後の状態 | 競合 / 権限不足 |
これは説明用の形です。実際のpathやstatus codeをそのまま採用せず、APIの既存契約、機密性、HTTP semanticsに照らして決めます。特に他者のresource IDを指定されたときに、存在の有無をどこまで明かすかはsecurity上の判断が必要です。
requestとresponseの契約を定義する
operationごとにpath parameter、query parameter、header、bodyの役割を分けます。必須・任意、nullの意味、enum、文字数や範囲、日付とtimezone、文字コード、ページングの境界を明記してください。request schemaでは形式だけでなく、検証エラーをどの単位で返すかも決めます。responseは必須field、nullable、配列の順序、resourceのversion、pagination cursorを定めます。
OpenAPIのschemaへ落とす際は、実装言語の型だけをコピーしません。wire formatで実際に送受信する値、互換性、default値、unknown fieldへの扱いを記述します。成功responseの例だけでなく、認証、権限、入力、対象不存在、競合、rate limit、依存先障害など代表的な失敗responseも載せるとclientの分岐を設計できます。エラー形式を既存サービスで標準化しているなら、その形式を再利用し、APIごとに別の構造を作らないようにします。
互換性と二重送信を設計に入れる
作成・決済・予約など、同じrequestを再送すると副作用が重なる処理は、timeout後のretryを想定します。idempotency keyを使うか、重複検出をどう行うか、同じkeyでpayloadが異なる場合にどうするかを定義します。すべてのPOSTで同じ仕組みが必要とは限りませんが、再送した場合の結果を未定義にしないことが重要です。
APIを変更するときは、既存clientが依存しているfield、error、順序、authentication、paginationの意味を先に確認します。追加fieldでも厳密schemaのclientでは破壊になる場合があり、削除や型変更は当然互換性リスクになります。versionを増やす前に、互換な拡張として実現できるか、移行期間やdeprecationが必要かを整理します。新しいendpointを作るなら、利用者、旧経路との並存期間、移行完了の判定も含めます。
認証・認可・データ露出
API設計では「誰か分かる」認証と「この操作をしてよい」認可を別々に定義します。利用者が自分の注文を見られることと、任意の注文をIDで取得できることは異なります。roleやtenant境界があるなら、一覧検索、個別取得、更新、exportで同じ境界を維持するか確認します。AIには認可表の叩き台を作らせても、resource ownershipやadmin例外は正本のpolicyに基づいて人が決めます。
request/responseへsecret、内部stack trace、不要な個人情報を含めないようにします。ログで何を記録するか、相関IDをどう渡すか、payloadをどこまで記録するかも設計対象です。rate limit、timeout、retry、外部依存障害時のfallbackを記載し、失敗が成功のように見える設計を避けます。これらの条件はシステムごとに異なるため、AIが作った標準らしい値をそのまま仕様にしません。
OpenAPIをレビュー可能な完成物にする
OpenAPIはHTTP APIのinterfaceを記述する仕様です。AIへ生成を頼む場合は、先にoperation表とschema案を確定し、その表からpathsやcomponentsへ変換させます。生成後にYAML/JSONとしてparseできること、operationIdが重複しないこと、参照が解決できること、responseが各operationに対応することを検証します。仕様ファイルがparseできることは、API実装が正しいことやsecurityが十分なことを意味しません。
レビューでは、各user actionから該当operationを逆引きできるか、必要なerrorが欠けていないか、同一概念のfield名や日付形式が揃っているかを見ます。APIを使う側が曖昧な独自解釈をしなくて済むかが基準です。表だけでなく、少数の具体的なrequest/response例を用意すると、nullableやエラー条件の認識差が表面化します。例は仕様に合う検証済みの値を使い、実在のtokenや個人dataを含めません。
小さな設計レビュー表
API案をreviewするとき、operationごとに以下を埋めます。
表は横にスクロールできます
| 確認欄 | 問い |
|---|---|
| 利用者と権限 | 誰が、どのresourceへ、何をしてよいか |
| 入力境界 | 必須値、範囲、形式、未知fieldの扱い |
| 成功契約 | status、response schema、識別子、状態変化 |
| 失敗契約 | validation、権限、未発見、競合、依存先失敗 |
| 再試行 | 同じrequestを再送したときの結果 |
| 互換性 | 既存clientへの影響、移行方法 |
| 運用 | log、相関ID、rate limit、timeout、監視 |
この表に答えられない項目は、空欄をAIに埋めさせず「未決定」として設計者に返します。特にsecurityとdata retentionは、コード生成で決めてはいけません。
AIものさしの判断
AIをAPI設計に使うなら、最初の生成物はendpoint一覧ではなく、action・resource・権限・contractの対応表です。そこからrequest/response、error、compatibilityを埋め、最後にOpenAPIへ落とします。RESTやversioningを先に決めるのではなく、既存clientとJobに必要なdataを満たし、変更の影響を検証できる設計を選んでください。
最後に最低限の確認を通す
AIの候補を仕様書へ取り込む前に、表の各operationが利用者の操作へ対応しているか、各fieldに定義と例があるか、成功と失敗の双方をclientが扱えるかを確認します。生成されたOpenAPI文書はvalidatorでparseし、参照切れやoperationの重複を検査できます。ただしvalidatorが示すのは文書構造の一部で、認可や業務上の正しさではありません。API ownerは代表的な利用場面を実装者と一緒に確認し、未決定のpolicyを仕様へ混ぜないようにします。