yohei-y:weblog

XML と REST/Web サービス関連の話題が中心の weblog です

2007-06-29

[これはすばらしい] mixi ステーション API。ただ一つ注文が…

via: mixi あしあとAPI発掘

mixi が Atom Publishing Protocl (APP) 対応の Web API を mixi ステーションで利用しているそうだ。

さっそく手元にあった APP クライアントで試してみると 30分くらいであっさりと接続成功。本当に素晴しい。 ざっくりと Web API を見させてもらったのだけれど、 拡張タグの使い方などセンスが良いし、さすがという感じだ。

ただ一点だけ、どうしても直してほしいのは APP の service document の名前空間 URI。 これは http://www.w3.org/2007/app が本番仕様である。mixi の Web API は古い名前空間を使ってる。 中の人はわかっていると思うんだけど、APP はもう少しRFC になる。 APP を実装する人は必ず RFC になる名前空間 URI を実装しましょう。 mixi の API を真似している人は気をつけてね。

ラベル: ,

2007-06-18

HTTP ステータスコードを正しく使おう

先月、ぐるなび 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 NoShop404 Not Found
601 Invalid Access403 Forbiddden
602 Invalid Shop Number400 Bad Request
603 Invalid Type400 Bad Request
604 Internal Server Error500 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 を作る上でどうあるべきか、という話です。

photo
WEB+DB PRESS Vol.39
WEB+DB PRESS編集部
技術評論社 2007-06-22

ラベル: , ,