WebAPIにおける独自ステータスコードの意味

「PlayFramework2 徹底入門」という本を読んでいるのですが、WebAPIの設計でよくわからないところがあります。
この本では、いわゆるRESTfulなAPI、すなわちhttpリクエストに対してJSON形式のデータを返すようなAPIについての紹介があります。
その時に返すJSON形式のデータの中に、整数型のエラー番号や、文字列型のステータス情報、サーバーから返すなんらかの付随情報を、ユーザが実際に使う情報とは別に作成しています。
例えば、こんな感じです。

JSON
1{
2    "code": 20,
3    "status": "ok.",
4    "message": null,
5}

この情報ってなんの役に立つのでしょうか？
本にはエラーコードのメッセージとして必要になると書いているのですが、そうすると、このAPIを使ってコードを書くときのエラーハンドリングの際に利用するようなものなのでしょうか？
しかし、返す時にhttpで定められたステータスコード(200がok、400がクライアントサイドのエラー、500がサーバーサイドのエラー）というのは、得られるわけで、それとは別に上で示した情報は必要になってくるのでしょうか？

行動規範の内容に同意します

回答2件

ベストアンサー

HTTPステータスコードで状態を返してもいいのですが、それだけでは細かい状態の区別ができない（たとえば、「商品をカートに追加できない」エラーを考えても、「商品の購入限度を超えた」「商品が売り切れた」「カート内の組み合わせがおかしい」など、いろいろな状態が考えられます）ので、アプリケーション独自でそれ以上に細かい区別を必要とする場合には、独自エラーコードが必要となります。

投稿2017/01/01 07:50

maisumakun

総合スコア145183

退会済みユーザー

2017/01/01 10:06

回答ありがとうございました。細かいハンドリングのためということですね。そういったステータスコードを含む細かい情報はアプリをリリースする際に、どのように示すのでしょうか？

maisumakun

2017/01/01 10:17

APIのドキュメントに書いておくことになると思います。

mit0223

2017/01/01 10:30

横から失礼します。API の場合、ドキュメントが重要です。そんなとき swagger はいかがですか？ http://swagger.io/ swagger でレスポンスを定義するならば、 http://swagger.io/specification/#responseObject

退会済みユーザー

2017/01/02 02:31

大変貴重なものをありがとうございました。

行動規範の内容に同意します

例えば、認証エラーであった場合、http としては正しく動作しているため、"200"を返します。
が、アプリケーションとしては認証エラーをクライアントに伝える必要があるため、その際 JSON 内にメッセージを埋め込むことで、アプリケーションとしての完成度を高めます。
受け取ったクライアントは、サーバサイドで認証エラーが発生知ることができるようになります。

といったように、レイヤーの違うところで利用されるものです。

投稿2017/01/01 07:05

退会済みユーザー

総合スコア0

退会済みユーザー

2017/01/01 07:09

認証エラーの場合は、403が返ってくるのではないでしょうか？

退会済みユーザー

2017/01/01 07:45

例をあげたのが悪かったですね。エラーを判断するレイヤーが違うと理解して下さい。 HTTP通信として、どのようなステータスであるかのメッセージがHTTPステータスコードで、その接続が正常に行われた上で、アプリケーションの挙動を知らせるメッセージがJSON内のデータです。 HTTPステータスコードが200以外の場合、JSONは返りません。

maisumakun

2017/01/01 07:53

必要があれば、200以外のステータスでレスポンスを返してもかまわないとは思います（30Xのリダイレクトや204 No Contentのようにレスポンスなしで返さないといけないものは除いて）。

退会済みユーザー

2017/01/01 08:00

"基本的に"ってつけようかと思ったのですが、更に混乱させるかと思いやめました。が、返しても良いかどうかで言うと返してもかまわないですね＾＾；

退会済みユーザー

2017/01/01 08:01

例としてあげたものの補足一般的には、エンドポイントのURLへのアクセス権限がない場合、HTTPステータスコードとして403を返し、リクエストとして送った電文内の認証が通らない場合、レスポンスで認証が通らなかった旨データとして記載します。

退会済みユーザー

2017/01/01 10:07

回答ありがとうございました。