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