RESTful APIのレスポンスデータ設計の最後でも述べたが、APIでエラーが発生した時のレスポンスデータも検討する必要がある。
エラー発生時のレスポンスデータの考え方
APIのレスポンスデータはほとんどの場合プログラムで処理されるため、エラーが発生した時も、
- どんなエラーが発生したのか
- そのエラーはなぜ発生したのか
- そのエラーはどうすれば解決できるのか
をプログラムが分かるようにしておく仕組みが必要。
エラー発生時のレスポンスデータ
1. HTTPステータスコードの設定
エラーが発生したら、レスポンスボディにエラー情報を設定するだけでなく、([RESTful APIのHTTPステータスコード設計]
(http://qiita.com/NagaokaKenichi/items/eb85b5fbb719d60c6627)でも書いた通り)適切なHTTPステータスコードを設定する必要がある(エラーが発生しているのに200を設定したりしないこと、200はリクエストが成功した時のみしか返してはいけない)。
2. レスポンスボディの検討
適切なHTTPステータスコードを設定すればOKなのかというとそれだけでは不十分。HTTPステータスコードはあくまでエラーのカテゴリや概要であり、冒頭で述べた
- どんなエラーが発生したのか
- そのエラーはなぜ発生したのか
- そのエラーはどうすれば解決できるのか
までを知ることは難しい。そのため、レスポンスボディに上記を設定してあげる必要がある。設定する情報としては、エラーコード、エラーの詳細情報またはエラーの詳細情報へのリンクがあれば、APIを利用する側に最低限の情報を伝えることができる。
以下は、TwitterとGREEのAPIのエラー発生時のレスポンスボディの例(参考:WebAPIでエラーをどう表現すべき？15のサービスを調査してみた)。
{
"errors": [
{
"message": "Bad Authentication data",
"code": 215
}
]
}
- message: エラーメッセージ
- code: エラーコード
{
"code":1001,
"message":"Message API (batch type) to same user is called
several times by official user in a certain period of time. Service unavailable.",
"ref_url":"http://docs.developer.gree.net/error.html"
}
- code: エラーコード
- message: エラーメッセージ
- ref_url: エラーの詳細が記述されたページのURL
※エラーコードとは、エラーの内容に応じた独自のエラーコード。
なお、レスポンスボディにエラー情報を設定する以外にも、独自ヘッダを定義してレスポンスヘッダにエラー情報を設定する、というやり方もあるが以下の理由により自分はレスポンスボディに設定したい。
- 個人的に独自ヘッダは好きでない
- 多くのAPIがレスポンスボディにエラー情報を設定している(参考:WebAPIでエラーをどう表現すべき？15のサービスを調査してみた)
エラー発生時のレスポンスデータの注意点
1. エラー発生時にHTMLを返さない
エラー発生時に、APIの構築に利用しているWebサーバやFWがデフォルトでHTMLをレスポンスボディに設定して返すことがある。APIを利用する側はAPIにリクエストしている以上、XML形式やJSON形式のレスポンスを期待しているので、HTMLを返されるとパースエラーが発生したりしてしまう。そういったことを防ぐためにも、エラー発生時にHTMLを返さないよう留意する必要がある。
2. メンテナンスとステータスコード
APIをメンテナンス等で停止することは極力避けるべきだだが、どうしても停止する必要がある場合は、HTTPステータスコードとして503を返しAPIが停止していることを伝える必要がある。もしメンテナンス終了時刻が分かっているのであれば、Retry-Afterヘッダー に終了時刻も設定することで、いつ頃になればメンテナンスが終了して通常通り稼働するかを伝えることが可能となる。