Rest 2

« Blogger + GDataとoptimistic concurrencyなど | メイン | Google不動産検索 »

2006年08月17日

RESTにおけるベストプラクティス: エラーハンドリング

[ Atom/REST ]

RESTfullなAPIにおいてのエラーハンドリングについては重要なのですが、今まで(特に日本では知っている限り)あまり言及されたことがなさそうなのと、オライリー系のサイトでたまたま今日良い記事 RESTful Error Handling を見つけたので、ココで紹介したいと思います。 (2003年12月の記事ですが何故か見落としていました)

この記事では、REPSfullなWebアプリケーションにおいて、エラーが発生した時の動作は(調査した所)一般的にいって4っつの方法が利用されているとしています。

1.HTTPステータスコードのみ

例えば、

http://www.example.com/xml/book?id=1234&dev_token=ABCD1234

のようなアドレスでGETした時、もし”id=”によって指定されたデータが見つからなかった場合、HTTPステータスコードの404 Not Found を返す、といった具合。2.空のレコードセットを返す

例えば、Atomフィードを返すようなケースで、エントリが一つもないフィード空フィードを返す。この場合、そもそも不正なIDなのか、単にまだ存在しないのかなどは分からない。

3.HTTPヘッダーを拡張する

HTTP/1.1 200 OK
…省略…
X-DAS-Status: 403
Content-Type: text/plain
Content-Length: 10
Date: Sun, 30 Nov 2003 21:02:13 GMT

上記のように、HTTPヘッダー内にアプリケーション固有のエラーコードを埋め込む。(注:確か偉い人がX-**のような拡張は安易に行なうべきではない、といった事を言っていました)

4.XML文書を返却する

<?xml version=”1.0″ ?>
<xoomleError>
<method>doGoogleSearch</method>
<errorString>Invalid Google API key supplied</errorString>
<arguments>
<hl>en</hl>
<ie>ISO-8859-1</ie>
<key></key>
<q>oreilly php</q>
</arguments>
</xoomleError>

のようなXML文書を返却して、エラーの詳細を通知する。

RESTにおけるベストプラクティスではRESTベースのWebサービスではどの方法がベストプラクティスと言えるのでしょうか、と筆者は問いかけ、未だベストプラクティスといえるものは無いようだと述べています。

しかし、もっとも重要なのは、「人間が読めるエラーの説明文」、「アプリケーション固有のエラー」、「機械処理できるエラーコード」であり、この三つのカテゴリを含む、少なくとも下記の条件を満たすのが大事なんじゃないかと述べています。

  1. HTTPステータスコードはHTTP通信に限ったエラーのために用い、アプリケーション固有のエラーには用いない。
  2. エラー発生時には、必ず詳細を含んだXML文書を返却する。
  3. XML文書にエラーコードと共に人間が読めるエラーメッセージを含めよ。具体的には下記の例:

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<error>
<error_code>1001</error_code>
<error_msg>不正な Google API キーです。</error_msg>
</error>

これを実践することによって、Webサービスは利用側の苦労は軽減し、問題が起きた時の対処も楽になる。エラーコードを元に適切な挙動をする事も出来る。

記事は大体上記の感じです。最後のまとめ部分は、100%同意する所です。以前、関連する事を、REST原理主義という微妙な記事で書いてしまいましたが、元々はAtom Publishing Protocolのワーキンググループ内での議論がきっかけでした。

個人的にAtom Publishing Protocolでエラーハンドリングのことが何も決まっていないのは問題だと思い、エラーフォーマットを提案していたのですが、大体において反応は、あると便利(4.XML文書を返却する)というのが多数、あるべきというのは少し、無いべき(1.HTTPステータスコードのみ )というのが少数だが激しく、という感じで結局、仕様には含めない、という事になっています。(このワーキンググループでは、異論があるのは本仕様外とする、という傾向が常々指摘されているw)

つまり、

「人間が読めるエラーの説明文」: なし(追記:正確にはリスポンスのボディに何かが返される場合がある。何かは極端な話×印の画像かもしれない。文字列だとしても、JSONかもしれないし、XMLかもしれないし、ただのテキストかもしれないし、Base64エンコードされているかもしれない。さらには文字コードの判定と変換といったWebブラウザ並の処理の手間がかかる。もしこれが特定のXMLフォーマットが返ると決まっていれば、これらの問題と手間はすべて解消される)

「アプリケーション固有のエラー」:: なし(追記:正確にはHTTPステータスコードで間に合わせる)

「機械処理できるエラーコード」: HTTPステータスコードで間に合わせる

という残念ながらベストプラクティスとはかけ離れたものとなってしまっています。最終的な希望は、Atomのコア仕様に含まれなくても、拡張仕様として後付けできるという事で、今後の試行錯誤で何らかのフォーマットが出来て、それにまとまっていくことが考えられます、というか強く希望しています。

なお、ホンモノのRESTベストプラクティスを読みたい方は、こちらのスライドをどぞ。

投稿者 BlogWrite担当 : 2006年08月17日 15:31

トラックバック

このエントリーのトラックバックURL:
https://www.witha.jp/b/mt-tb-hate-spam.cgi/390

コメント

コメントしてください

TypeKey ID を使って サイン・イン してください。

Previous article

Post 26

Next article

Post 17