Edited at

RESTful APIのHTTPステータスコード設計

More than 3 years have passed since last update.


HTTPステータスコード設計

RESTfulなAPIでは、以下の理由によりAPIの処理結果は適切なHTTPステータスコードを利用することが推奨されている。


  • 適切なHTTPステータスコードを返さないと、レスポンスボディの中身を解析して処理結果を判定する必要がある

  • HTTPの標準仕様を使うことで、HTTPステータスコードから処理結果を判定することができる

  • HTTPの標準仕様を使うことで、APIを利用する第三者にとっても理解しやすくなりバグの混入を減らすことができる

  • ほとんどのHTTPクライアントライブラリはHTTPステータスコードを見てリクエストが成功したか、失敗したかを判別している

※ステータスコードは一律200で処理結果をレスポンスボディで表現するようなことはしてはいけない。例えば、API側で内部エラーが発生し本来であれば500(INTERNAL SERVER ERROR)を返さなければいけないところを、200で返して内部エラーが発生したという結果をレスポンスボディで表現するようなことはしてはいけない。

そのため、どのような場合にどのようなステータスコードを返すかを検討する必要がある。


よく使われるHTTPステータスコード

一般的に以下のようなステータスコードがよく利用される。実際に設計する際は、APIが提供する機能によってどのようなステータスコードを利用するかを検討する(例えば、提供するAPIがPOSTリクエストを提供しないのであれば201を利用する必要はない、、等)。また、仕様が煩雑になるのを防ぐためにも、極力必要最低限のステータスコードを利用する。

ステータスコード
名前
説明

200
OK
リクエストは成功しレスポンスとともに要求に応じたリソースが返される。

201
CREATED
リクエストは完了し新たにリソースが作成された。Locationヘッダには新たに作成されたリソースのURIが含まれる。POSTで利用される。

204
NO CONTENT
内容なし。リクエストを受理したが、返すべきレスポンスエンティティが存在しない場合に返される。PUT、POST、DELETE等で利用される。

303
SEE OTHER
他を参照せよ。リクエストに対するレスポンスが他のURIとして存在するときに返される。Locationヘッダに移動先のURIが示されている。

400
BAD REQUEST
リクエストが不正である。定義されていないメソッドを使うなど、クライアントのリクエストがおかしい場合に返される。

401
UNAUTHORIZED
認証が必要である。Basic認証やDigest認証などを行うときに使用される。

404
NOT FOUND
未検出。リソースが見つからなかった。

405
METHOD NOT ALLOWED
許可されていないメソッド。許可されていないメソッドを使用しようとした。

409
CONFLICT
競合。リクエストは現在のリソースと競合するので完了出来ない。

500
INTERNAL SERVER ERROR
サーバ内部エラー。サーバ内部にエラーが発生した場合に返される。

503
SERVICE UNAVAILABLE
サービス利用不可。サービスが一時的に過負荷やメンテナンスで使用不可能である。


HTTPステータスコード一覧

https://tools.ietf.org/html/rfc7231#page-50

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html