» Permanent link
|
|
先月、
ぐるなび API
がリリースされていました。
ぐるなびさんの持っている膨大なデータベースに Web API を通して気軽にア
クセスできるようになったのは、非常に喜ばしいし、その英断に感謝したいと
思います。
しかし、Web API 仕様書、特にエラー仕様を見てちょっとがっかりしました。
もう少し上手にデザインすれば、もっとよかったのに…、という思いです。
一度出してしまった API はそう簡単に変えられないと思いますが、
参考までに僕だったらどうするか、を書いてみます。
この仕様の一番の問題はエラーコードです。
以下は 2-2 のエラー仕様に記述されているサンプルです。
<?xml version="1.0" encoding="UTF-8"?>
<gnavi>
<error>
<code>602</code>
</error>
</gnavi>
タグが三つ(gnavi, error, code)出てきます。
重要なのは code だけで、ここにエラーコードが入ります。
602 というコードは Invalid Shop Number を示します。
エラーコード一覧を見ると、現在五つのコードが定義されていることがわかり
ます。
よくない点を一言で言うと、エラーコードを再発明してしまっているということです。
たとえば 604 は "Internal Server Error" なんですが、
このフレーズに覚えがありませんか? そう HTTP の 500 Internal Server
Error と同じです。HTTP で 500 を返せばいいところを、
独自 XML 形式でしかも 604 という独自のエラーコードを再発明しています。
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<gnavi>
<error>
<code>604</code>
</error>
</gnavi>
本来はこうあるべきです。
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
処理中にエラーが発生しました。
なぜエラーコードの再発明は駄目なのでしょうか。それは専用のクライアントが必要になる
からです。単なる HTTP クライアントではなく、ぐるなびのエラーコードを実
装した専用クライアントが必要になってしまうからです。専用クライアントが
必要なので、その分余計なコードが必要となって、障害が発生する確立も上り
ます。
参考までに、ぐるなび API のエラーコードを HTTP のステータスコードにマッピングしてみました。
| gnavi エラーコード | HTTP ステータスコード |
|---|
| 600 NoShop | 404 Not Found |
| 601 Invalid Access | 403 Forbiddden |
| 602 Invalid Shop Number | 400 Bad Request |
| 603 Invalid Type | 400 Bad Request |
| 604 Internal Server Error | 500 Internal Server Error |
601 は通常は 401 Unauthorized にしたいところですが、
ぐるなび API は api key 方式を採用しているので 403 にしてみました。
また、この対応により 602 と 603 が 400 にまとめられてしまっていますが、
両者の違いは HTTP のレスポンスボディで記述すればいいでしょう。
もし、この二つを区別する理由が、エラーメッセージを出すためだけであれば、
メッセージそのものをプレーンテキストで返せばいいのです。
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
指定された店舗の情報が存在しません。
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
不正なぐるなび店舗IDパラメータが指定されました。
WEB+DB Press の今月号には、まさにこの話を書きました。
本文とコラムが同じくらいのページ数という、一時期の JavaWorld の檜山さ
んみたいな構成ですが、
普段なにげなく使っている HTTP のステータスコードは
Web API を作る上でどうあるべきか、という話です。
ラベル: books, http, rest
