Hatena::ブログ(Diary)

winplusの日記 このページをアンテナに追加 RSSフィード

2012-07-06

Web API Design(その6:終)

これno titleの勝手訳のつづき。これでおしまい。

追記id:tkawaさんのブックマークコメント「おしゃべりな(chatty)APIはダメ。これけっこう重要」。これについては、以前の翻訳記事RESTfulアプリケーションのパフォーマンス - winplusの日記も、ご参照ください。

おしゃべりなAPI

あなたのデザインしたAPIを - おしゃべりなAPIをデザインし手がけているとして - アプリケーション開発者がどう利用するか、考えましょう。

開発者がAPIを利用しようとしているところを思い浮かべる

APIとリソースをデザインするとき、開発者がどのようにそれを使うのか思い浮かべるようにしてください。開発者はAPIを使って、ユーザーインターフェイス、iPhoneアプリケーション、あるいは、それ以外のたくさんのアプリケーションを構築しようとしています。

デザインがとてもおしゃべりになっているAPIがあります - おしゃべりというのは、単純なUIあるいはアプリケーションを組み立てるだけのために、サーバーへ数ダースあるいは数百のAPI呼び出しをおこなうということです。

APIチームはしばしば、ナイスでリソース指向であるRESTful APIは手がけない、と決定することがあります。そして、特定のユーザーインターフェイスでのみ動作するような3つか4つのJava様式のgetter/setterメソッドをつくるとやり方へと、たんに後退します。

これは推奨しません。RESTful APIをデザインして、おしゃべりを減らしてください。

完全にしてください、RESTfulにしてください、ショートカットを提供してください

まずはじめに、実用的RESTfulデザインの原則にしたがってAPIとそのリソースをデザインしてください。そのあと、ショートカットを提供してください。

どんなシュートカットを? ご存知のとおり、アプリケーション全体の80%が、ある種の複合リソースを必要としていると言われています。ですから、それらが必要とするものを提供するようなリクエストをつくってください。

前者のかわりに後者のみをおこなわないでください。まずはじめに、適切な実用的RESTfulデザインの原則をつかってください!

部分的なレスポンスの構文を利用する

前のセクションで議論した部分的なレスポンスの構文は助けになります。

一度限りのベースURLを作成することを避けて、依存あるいは関連しているリソースへと掘り進むために、部分的なレスポンスの構文を使うことができます。

犬(dogs)APIだと、犬は飼い主と関連付けられており、同じく飼い主は獣医と関連付けられており、などなど。部分的なレスポンスの構文に入れ子にしてドット表記をつかってください。ドット表記で必要とするその情報までたどってください。

/owners/5678?fields=name,dogs.name

SDKをつかって補完する

コードのライブラリとソフトウェア開発キット(SDK)をつかって、APIを補完する必要がありますか? これはAPI提供者にとって、よくある疑問です。

もしAPIが適切なデザインのプラクティスにしたがっているのであれば、つまり、自己矛盾がなく、標準にもとづいており、十分にドキュメント化されていれば、開発者はクライアントのSDKがなくても軌道に乗ることができるでしょう。また、じゅうぶんにドキュメント化されたコード例は貴重な資源です。

いっぽうで、たくさんのドメイン知識を必要とするUIを構築するというシナリオについてはどうでしょうか? これは開発者にとって困難な課題になるでしょう。かなりシンプルなドメインをつかったUIとアプリケーションを構築する場合でさえ - 140文字のテキストを中心とするTwitter APIを考えてください - そうでしょう。

ドメイン知識のハードルをこえるために、APIを変更しようとしてはいけません。そのかわりにコードライブラリとソフトウェア開発キット(SDK)とをつかって、APIを補完してください。

このやり方はAPIデザインに余分な負担をかけません。クライアント側でおおくのものが必要となることがしばしばありますが、SDKにその負担を押しつけることができるのです。

SDKではプラットフォーム固有のコードを提供することができます。開発者はAPIの操作を呼び出すために、アプリケーションでそのコードを使います - そして、APIはきれいなままです。

APIにSDKを含めて補完することを検討すべき、その他の理由を次にあげます。

特定のプラットフォームでの採用を促進します。たとえばiPhoneのためのObjective C SDK)。経験を豊かな開発者がたくさん、まさにいま、objective C+を使いはじめています。だから、SDKは役に立つに違いありません。

APIをつかって動かすために要求な組み込みのための手間を簡単にしてください。 - もし、主なユースケースが複雑であったり、クライアント上での処理を標準化して補完する必要があるものであったりするのであれば。

SDKは低品質なあるいは効率の悪いコードを減らしてくれます。そのようなコードは利用者全員へのサービスの速度を低下させてしまうかもしれません。

開発者のリソースであると同時に - よいSDKは高品質のソースコードサンプルやドキュメントを作成するように強制する役割をはたします。Yahoo!とPaypalがよい例です。

Yahoo! http://developer.yahoo.com/social/sdk/

Paypal https://cms.paypal.com/us/cgi-bin/?cmd=_rendercontent&content_ID=developer/library_download_sdks

APIをあるコミュニティに売り出すために - プラットフォームにある開発者コミュニティ上の、サンプルあるいはプラグイン・ページに、SDKをアップロードするのです。

APIファサード・パターン

現在のところ、次のように疑問をお持ちかもしれません。

アーキテクチャー上の全体像という視点からは、なにを考えるべきなのでしょうか?

これらのベストプラクティスすべてにしたがうには、どのようにすればよいでしょうか?アプリケーション開発者に役立つやり方で内部的なサービスとシステムを公開するには、どうすればよいのでしょうか? さらに、APIを繰り返し改善し、維持していくためには?

バックエンドの記録システムがあまりに複雑すぎて、そのままアプリケーション開発者には公開できないこともよくあります。安定していて(時とともに堅牢になってきました)、信頼性がありますが(ビジネスの重要な側面で稼働しています)、でも、しばいしば古くさい技術にもとづいていて、HTTPのようなWebの標準として公開するのは容易ではありません。また、これらのシステムは入り組んだ相互依存性をもっていることがあり、ゆっくりとしか変更できません。つまり、モバイルアプリケーションの開発者が要求する素早さでは動けないし、フォーマットの変更についていくこともできないのです。

ようするに、たったひとつの大きなシステムのAPIを作成しているのはなく、開発者にとって価値のあるAPIをつくるために必要となる一連の補完的なシステムのAPIを作成するというのが、この課題です。

[図]

私たちがみてきた2、3のアンチパターンをつうじて話す内容は、役に立つでしょう。それらがうまくいかない理由だと信じていることを、みてください。

ビルッドアップ・アプローチ

ビルッドアップ・アプローチでは、開発者は、大きなシステム手の中心のオブジェクトを公開します。そして、いちばん上にXML構文解析のレイヤーを置きます。

[図]

このアプローチは素早くバージョン1を売り出すことができるという利点があります。また、APIチームのメンバー(内部の開発者)は、内部システムの詳細をすでに把握しています。

残念ながら、オブジェクトレベルでの内部システムの詳細は粒度が細かすぎて、外部の開発者が混乱してしまうかもしれません。また、内部アーキテクチャーの詳細を公開しています - これがいいアイデアであることはほどんどありません。システムがどう動作するかと、APIをどう公開するかとが1対1で対応しているために、このアプローチは融通がきないことがあります。いいかえると、記録システムからAPIを組み立てることが、あまりに煩雑すぎるようになることがあるのです。

標準規格委員会アプローチ

内部システムが異なった人たちあるいは部署によって所有され、維持されていることがよくあります。これらの人たちあるいは部署は、ものごとがどう動作すべきかについて異なった見解をもっています。標準規格委員会によるAPIのデザインは、スキーマ、URL、その他を定義する標準規格ドキュメントの作成を含むことがよくあります。すべての利害関係者が共通のゴールにむかって集結します。

[図]

このアプローチの利点には、素早くバージョン1を手に入れることが含まれます。また、組織を横断した統一と、包括的な戦略の意識をつくりだすことができるかもしれません。数多くの利害関係者や投資家による大きな組織にいるばあいは、これが重要な成果になることもあるでしょう。

標準規格委員会アプローチの欠点は、それが遅いことがあるということです。たとえあなたが素早くドキュメントを作成したとしても、全員がそれを実装するのは遅くなることがありますし、忠実に守られないこともあります。また、このアプローチは、あまりにおおくの妥協の結果、二流のデザインにつながることもあるでしょう。

ものまねアプローチ

組織が売り出しに遅れているとき - たとえば、類似の競合相手がすでにソリューションを提供しているとき - このパターンを目にすることがあります。繰り返しますが、このアプローチは、素早くバージョン1を手に入れることができます。そして、あなたのAPIをつかうであろうアプリケーション開発者がすでに競合相手のAPIをよく知っているのであれば、すでにある採用者分布曲線を手にすることができるかもしれません。

[図]

しかしながら、API市場で粗悪品を提供していると見なされ、差別化できない製品として終わってしまうことがあるでしょう。ほかの誰かのAPIデザインをたんにコピーすることで、あなた自身のキーとなる価値と差別化を提供することに失敗してしまうかもしれません。

解決方法 - APIファサードパターン

もっともよい解決方法は、製品管理の原理について考えることから始まります。あなたの(API)は、信頼性があり、妥当であり、差別化されていなければなりません。プロダクトマネージャーはAPIチームのキーとなるメンバーです。いったんプロダクトマネジャーが全体像がどのようなものであるかを決定すれば、あとは設計者次第です。

私たちはAPIファサードパターンでの実装を推奨します。このパターンは、いちばん上のインターフェイスといちばん下のAPI実装とのあいだに、バッファーあるいは仮想レイヤーを提供します。あなたは原則的にファサードをつくります。ファサードとはAPIがなにであるかの包括的な見え方であり、そして重要なことに、アプリケーション開発者と彼がつくったアプリケーションの最終利用者から見えるものなのです。

[図]

開発者とAPIをつかうアプリケーションとは、いちばん上に位置します。APIファサードは、開発者とアプリケーションとAPIとを分離します。ファサードできれいにデザインすれば、ひとつの本当に困難な課題を、いくつかの単純な課題へと分解することができます。

「複雑なサブシステムにたいして単純なインタフェースを提供したいとき、ファサードパターンを使用してください。サブシステムは発展するにしたがって、より複雑になることがよくあります。」

オブジェクト指向における再利用のためのデザインパターン

(Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides)

APIファサードパターンの実装は、3つの基本的なステップを含みます。

  1. 理想的なAPIをデザインしてください - URL、リクエストパラメター、レスポンス、ペイロード、ヘッダー、クエリーパラメータなど。 APIデザインは首尾一貫しているべきです。
  2. データのスタブをつかってデザインを実装します。 これで、APIが内部システムに接続される前であっても、アプリケーション開発者はAPIをつかうことができますし、フィードバックを返すこともできます。
  3. ファサードとシステムとの間を仲介あるいは統合します。

[図]

3段階のアプローチをつかって、ひとつの大きな課題を3つのより小さな課題に分解したところです。もしひとつの大きな課題を解決しようしているのであれば、ビジネスロジック(記録システム)からきれいなAPIのインターフェイスを組み立てようとして、コードにとりかかっているでしょう。それぞれのサイロからオブジェクトやらテーブルやらRSSフィードやらを、それぞれ正しいXMLに変換した上で、公開しようとしているでしょう。これはアプリケーションのまわりに焦点をしぼったマシン同士のやりとりへ方を向いています。そして、これをちゃんとやりとげるのは困難です。

ファサードパターンを採用することは、たくさんの重要な方法で、サイロアプローチから考え方をかえる手助けをします。まず最初に、3つの分離したステップのそれぞれで、いろいろと仕入れることができます。そして、デザインにたいしてどのように実用的なアプローチをとっているのかを人びとによりはっきりと分かってもらうことができます。2番目に、方向性をアプリケーションから開発者へと変更します。アプリケーションの開発者があなたのAPIをつかえることを保証すること、これがゴールになります。そのためには、デザインが首尾一貫かつ直観的でなければなりません。

このアーキテクチャーにはそれがあるので、ファサードは興味深いゲートウェイになります。よくあるパターンの処理(ページ送り、クエリー、並び順、並べ替え、他)、認証、認可、バージョン付け、などなどをAPIをこえて統一的に実装したファサードを、いまや手に入れることができるのです。(APIをこえた統一性は大きな話題で、十分に議論することはこの記事の範囲をこえています。)

ほかの利点としては、APIチームが異なったユースケースにより手軽に対応できることがあります。内部の開発者のシナリオであるか、パートナーのシナリオであるか、誰でも参加できるシナリオであるかにかかわらず、です。APIチームは開発者の要求が変われば、絶えず変化しているプロトコルやプログラム言語も含めて、それについていくことができるでしょう。さらにまた、業務システムからよりおおくの機能を構築することで、あるいは既存のシステムを追加することで、APIを拡張することもより簡単になります。

kskyksky 2013/04/23 12:09 突然すみません、Apigeeに日本支社ができ、"Web API Design"の日本語版を作ろうとしています。よろしければご一報いただけないでしょうか。

トラックバック - http://d.hatena.ne.jp/winplus/20120706/1341585690