» 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 を作る上でどうあるべきか、という話です。 WEB+DB PRESS編集部 技術評論社 2007-06-22

ラベル: books, http, rest