InfoQのRESTについての興味深い議論のすぐ後に、George Reese氏が面白い記事を書いた。REST APIの良い、悪い、醜いと題したこの記事で、氏はREST API開発ですべきこと、すべきでないことを論じている。
REST API作成の推奨事項の中でも、氏は次の点を強調する。
- APIモデルをデータの利用の仕方に合わせること。データ/オブジェクトモデルに合わせないこと。
APIコールで得られるデータはデータベースのテーブルを高度に標準化したものであってはなりません。データはAPIの利用者が理解できるように表現されていなければなりません。
これはSOAの元のデータアクセスモデルからメッセージモデルを分離するという原則と似ている。
- 理解可能なエラーメッセージも有用だ。APIを作るとき必要なのは、
利用者のAPIを学ぶ上で 起こす失敗をすべて考慮しておくことです。
そして、何が間違っていたかの詳細な説明を返すことだ。このような説明の良い例がこの素晴らしいスライドで紹介されている。
- APIのドキュメントがしっかりしていると利用者は自己解決しやすい。
しっかりしたAPIドキュメントがあると、簡単な例を元に利用方法を学ぶことができますし、高度な問題解決に複雑な方法でAPIを利用する場合にも便利です。
- 安全なAPIを適切に使う。例えば、RESTでよく使われているOAuth認証は、ブラウザをターゲットにAPIを提供している場合は上手く動作するが、システム間の連携では適用できない場合が多い。このREST APIの安全性については"RESTful API の 認証の枠組"という記事でも議論している。
- RESTはいい、SOAPはダメ。氏の考えでは
利用者が様々な言語で利用する場合、SOAPは本当に実装するのもサポートするのも大変です。
さらに氏は次のように断言する。
JSONはいい、XMLはだめ
したがって、JSONをサポートするRESTはXMLを強制するSOAPよりも優れているということだ。この点については、Gerald Loeffler氏が"RESTはエンタープライズで成功しているか？"という記事に対するコメントで論じている。
... 純粋に技術的な基準で比較検討しないと、その技術領域が求める厳密さを失ってしまいます。... ひとつの見方(イデオロギーといってもいいかもしれません。WS-*、REST、動的型、静的型などに対する信仰です)に没入すればするほどそれが真実だと思い込んでしまいます。そして、絶対的な真理になってしまいます。でもそれは違うのです。それはひとつの見方であり、ある出来事(それも特定の性質と属性を伴った出来事です。純技術的な議論が必要なのはこのためでもあります)に対する論理的な解釈にすぎません。残念なことにソフトウエア開発では、あるひとつの一方的な視点からの主張が他方の考えを馬鹿にしている場合が多いです。"わかってないな"という具合に。
氏が言うには、REST APIを作る上で悪い(そして醜い)のは、
- APIの呼び出し回数を制限するのは危険。
制限するつもりなら、... とても賢い実装が必要です。つまりa)テストや定期的な呼び出しを行って合理的な制限値を見つけ、b)間違って制限してしまうことの悪影響を最小限にとどめる必要があります。"思いつき"で制限するのではなく、利用者への影響を考慮すべきです。
- うるさいAPIはダメ。氏によれば、うるさいAPIとは利用者がひとつの一般的な処理を行うのに一回以上の呼び出しが必要なAPIのことだ。うるささを構成要素は、もちろん、利用者がそのAPIで何をしたいのかに依存する。
- HTML形式のレスポンス。氏は、APIサーバと通信ができない状態でも、サービスは常に有効なJSON/XML形式でレスポンスを返すべきだと主張する。
APIの利用者がまだHTMLを受け取っているとしたら、とても、とても、悪いことをしていると思うべきです。
- 500エラーの副作用は悪。APIは500を返すエラーが冪等であることを保証しなければならない。エラーが発生した処理での変更はロールバックされなければならない。
氏のブログにはREST API実装についてのしっかりとしたベストプラクティスが紹介されている。すべきこと、すべきでないことに加えてなぜそうすべきか(すべきでないか)も説明されている。根拠も紹介されているのだ。このベストプラクティスが有効なのはRESTだけでない。RESTのデザインやリソースの定義、パラメータの正しい受け渡し方などには言及していないが、どんなAPIにでも有効な実装方針だ。