『Web API Design -Crafting Interfaces that Developers Love-』の翻訳③

＊作成中ですが、諸事情により一時的に公開＊

 

Consolidate API requests in one subdomain

我々はトップレベルドメインの後のことについて話をしてきた。今度は、URLの別の側面についてのstuffを詳しく見てみよう。

ここでは、Facebook、Foursquare、Twitterがこれをどのように扱っているかを見てみる。

Facebookは二つのAPIを提供している。api.facebook.comから始まるものと、ソーシャルグラフ向けに修正をしたgraph.facebook.comから始まるものである。

  • graph.facebook.com
  • api.facebook.com

Foursquareは一つのAPIを持つ。

  • api.foursquare.com

Twitterは三つのAPIを持つ。二つはサーチとストリーミングに焦点を合わせたものである。

  • stream.twitter.com
  • api.twitter.com
  • search.twitter.com

FacebookとTwitterがどのように一つ以上のAPIを持つようになったかは容易に理解できる。timingとacquisitionと共にやることが数多くあり、リクエストを異なるクラスタへ指し示すように、あなたのDNSのCNameエントリを再設定することが容易である。

しかし、我々がアプリ開発者の最大の利益が何かについてのデザインの決定をするのであれば、我々は以下のFoursquareのリードをおススメする。

Consolidate all API requests under one API subdomain.（すべてのAPIリクエストはAPIサブドメインの下に集約しなさい）

あなたのAPIを使ってクールなアプリを作ってほしいとあなたが思っている開発者にとっては、これがより綺麗でかつ簡単、直感的である。

Facebook、Foursquare、Twitterはすべて、専用の開発者ポータルを持っている。

  • developers.facebook.com
  • developers.foursquare.com
  • dev.twitter.com

これを全部体系化するにはどうすればよいか？

あなたのAPIのゲートウェイは、ドメインのトップレベルにあるべきである。例えば、api.teachdogrest.comのように。

RESTの精神をキープするため、あなたの開発ポータルはこのパターンに従うべきである：developers.yourtopleveldomain。例えば、developers.teachdogrest.comのように。

Do Web redirects

さらに、もしあなたがブラウザからやってきたリクエストから、開発者が本当に行く必要がある場所がどこかを感知することができれば、あなたはリダイレクトすることができる。

開発者がブラウザでapi.teachdogrest.comと打ち込んだが、GETリクエストに対して何の情報もないと言うのであれば、あなたは安全にあなたの開発者ポータルにリダイレクトし、開発者が本当に必要としている場所へ到達する手助けができるだろう。

  • api -> developers (if from browser)
  • dev -> developers
  • developer -> developers

Tips for handling exceptional behavior

これまでのところ、我々はベースライン、標準的な振る舞いを扱ってきた。

ここでは、我々は起こりうる例外について詳しく見てみる。すわなち、Web APIのクライアントが、我々が議論してきたすべてのものを扱えないときである。例えば、クライアントはHTTPのエラーコードをインターセプトしたり、限定されたHTTPのメソッドのみをサポートしたりすることがある。

これらの状況を扱い、また特定のクライアントの制限下において機能するようにするには、どのような方法があるだろうか？

When a client intercepts HTTP error codes

Adobe Flashのいくつかのバージョンに共通するものとして、もしあなたがHTTP 200 OK以外のHTTPレスポンスを送ったら、Flashコンテナはレスポンスをインターセプトし、アプリのエンドユーザの前にエラーコードを置く。

それゆえに、アプリ開発者はエラーコードをインターセプトする機会を持たない。アプリの開発者は、APIがこれをどうにかしてサポートすることを必要としている。

Twitterはこれを扱うためにすばらしい仕事をしている。

彼らはsuppress_response_codesというオプション・パラメータを持っている。もしsuppress_response_codesがtrueにセットされていたら、HTTPレスポンスは常に200になる。

  • /public_timelines.json?suppress_response_codes=true
  • HTTP status code: 200{“error”:”Could not authenticate you.”}

このパラメータはとても詳細なレスポンス・コードになっていることに注意されたい（それらはsrcのようなものを使ったかもしれないが、彼らは冗長にすることを選んだ）。

これは重要なことである。というのも、あなたがURLを見るとき、あなたはそのレスポンス・コードが抑えられたものであることを理解する必要がある。それは、アプリがどれに対してどのように応答しようとしているかについて、大きな暗示を持つものなのである。

Overall recommendations:

1. suppress_response_codes = true を使う

2. HTTPコードはもはや

我々の以前のHandling Errorの章でのルールは変わる。このコンテキストでは、HTTPのコードはもはやそのコード（プログラム）のためのものではなく、無視されるべきものである。クライアントのアプリはHTTPのステータスコードをチェックすることはなく、いつも同じである。

3. 我々がHTTPレスポンスの中に置くであろう、どのようなレスポンス・コードも、レスポンス・メッセージの中に押し込みなさい

私の以下の例では、レスポンス・コードは401である。あなたはレスポンス・メッセージの中で、それを見ることができる。

付加的なエラーコードと詳細な情報も、そのメッセージの中に含まれる。

When a client supports limited HTTP methods

GETとPOSTはサポートするが、PUTとDELETEはサポートしないというのを見るのは一般的である。

四つのHTTPメソッドの完全性を維持するために、我々はRuby on Ralisの開発者によって一般に使われている、以下のやり方を使うことを提案する。

Make the method an optional parameter in the URL.（URLの中のオプション・パラメータでメソッドを作る）

そのとき、HTTPの動詞は常にGETになるが、開発者はHTTPの豊富な動詞を表現し、RESTfulでクリーンなAPIを維持することができる。

WARNING：GETメソッドを使ってpostやdeleteの機能を提供することは危険になり得る。というのも、URLがWebページにあれば、GooglebotのようなWebクローラーが不注意に大量のコンテンツを生成または破壊することができてしまうのである。あなたが自身のアプリケーションのコンテキストのたいしてこのアプローチをサポートすることで引き起こされるであろう結果について、自身が理解しているかを確認しなさい。

Authentication

多くの考え方の流派が存在する。Apigeeにおける私の同僚と私とでは、いつも認証の扱い方について合意するとは限らない。しかし、全体として、ここでは私がとっている方法を紹介する。

これらの三つのトップ・サービスについて見てみよう。これらのサービスが、それぞれどのような対応の違いがあるかを見ましょう。

  • PayPal … Permission Service API
  • Facebook … OAuth 2.0
  • Twitter … OAuth 1.0a

PayPayの所有するthree-legged permission APIは、OAuthが考えられる前に長く実施されていたものであることに注意されたい。

あなたはどうするべきか？

最新で最高に良いOAuthである、OAuth2.0（これを書いている時点）を使いなさい。それはつまり、APIを公開しているWebやモバイルアプリはパスワードを共有する必要がないということである。それによって、APIの提供者は、ユーザに元々のパスワードを変更することを要求することなく、アプリ全体に対して、個別のユーザについてのトークンを呼び戻すことができる。これは、モバイル機器が危険にさらされたり、不正なアプリが発見されたりしたときに重大な意味を持つ。

なにより、OAuth 2.0はセキュリティの改善と、Webとモバイルアプリでのエンドユーザと消費者のよりよいエクスペリエンスを意味する。

OAuthに似ているが異なっていることはしてはいけない。あなたのバリエーションによって、アプリの開発者が自身の言語でのOAuthライブラリを使用できないということになったら、それはアプリの開発者にとってフラストレーションとなる。

Chatty APIs

アプリ開発者が、あなたのデザインしているAPIをどのように利用しているかを考え、おしゃべりなAPIに取り組んでみよう。

Imagine how developers will use your API

あなたのAPIとリソースをデザインするときには、開発者が、iPhoneアプリやその他多くのアプリ、ユーザ・インタフェースを構築すると言う際に、どのようにそれを使うかを想像してみなさい。

APIデザインの中には、とてもchattyになっているものがある。すなわち、シンプルなUIまたはアプリを作るために、何十何百のAPIコールをサーバに送るということである。

APIチームは、ナイスでリソース指向のRESTful APIを作る事に取り組まないことを決め、彼らが特定のユーザ・インタフェースpowerする必要があると知っている三つか四つのJavaスタイルのゲッターとセッターメソッドを作るモードに

 

 

お勉強

Posted by hidaka_hiroji