# Web API 設計標準
OpenAPI Specification 規約を利用するに当たり、想定する Web API の設計ルールをまとめる。このルールに必ずしも準じる必要は無いが、このような設計を暗黙的に考慮し OpenAPI Specification 規約を作成している。
# HTTP メソッド
実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。
# HTTP ステータス
RFC 7231 (opens new window)で定義されているレスポンスステータスコードを利用します。
RFC9205 (opens new window)（日本語訳 (opens new window)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。
# 共通
- バリデーションエラー：
400 Bad Request - 業務エラー：
400 Bad Request - 認証エラー：
401 Unauthorized - 認可エラー：
403 Forbidden - システムエラー：
500 Internal Server Error
# GET
- 正常系：
200 OK- 検索系 API で結果 0 件の場合も、
200 OKを返すとする
- 検索系 API で結果 0 件の場合も、
- パスキー検索系 API で対象リソースが存在しないエラー：
404 Not Found
# POST
- 正常系（同期）：
201 Created - 正常系（非同期）：
202 Accepted - 一意制約違反エラー：
409 Conflict - 親リソースが存在しないエラー：
404 Not Found
# PUT
- 正常系（同期）：
200 OK - 正常系（非同期）：
202 Accepted - 対象リソースが存在しないエラー：
404 Not Found
# DELETE
- 正常系：
204 No Content- もし、削除した項目の情報を応答する場合は
200 OKとする
- もし、削除した項目の情報を応答する場合は
- 対象リソースが存在しないエラー：
404 Not Found
# API バージョン管理
- /v1, /v2 といったパスで表現する
- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する
# パラメータの命名
boolean 型である場合、 [a-zA-Z0-9-_]+_flag という命名は非推奨とする。
is_[a-zA-Z0-9-_]+ や has_[a-zA-Z0-9-_]+ などの命名を代わりに検討する