184
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

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

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
184
Help us understand the problem. What are the problem?