# 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-_]+
などの命名を代わりに検討する