http://apigee.com/about/content/api-fa%C3%A7ade-pattern
API Facade Pattern Design backendと内部システムがapplication開発者にそのまま晒すには複雑すぎる場合のAPI設計
app devはAPI teamから提供された複雑なものを、匠の技でそのままつかっているケースがおおい
つまり、必要なのは一つの大きなシステムではなく、お互いがお互いを補いあうようなシステムであり、それを用いてAPIをapp devにとって価値のあるものにすること
API Facade Pattern
エラー処理
欲しいHTTP statusコードを決める
大体この8つで構成する
200, 201, 304, 400, 401, 403, 404, 500

{
"deleloperMessage": "hogehgoe",
"userMessage": "hogehoge",
"errorCode": 12121,
"status": 401,
"moreInfo": "docs url"
}client側がテストしやすいように、development環境で
GET /prouducts?raise500
みたいにするとエラーがかえってくる仕組みにするのもあり
You've designed your set of HTTP codes from the outside in. You have a big internal system, which let's say was built on the .NET framework. Microsoft has an extension of the HTTP status codes - 449 Retry With. You will want to map the 449 to something more aligned with what mobile developers are familiar with today. To do so, you can implement a lookup table and transform the 449 code into a 404 error.
内部の複雑なエラーコードを、(449みたいな)をdeveloper friendlyな形にラップしてやる(449→404みたいに)
Responses and data stubs
facadeシステムはbackendのシステムと独立していて、テスト環境では本来返すはずのデータのスタブを返す。
In the same way we designed the forced raise for errors, you can force the mock. Setting mock = true, you have a shunt in the facade that returns the stub. Again, we're looking at predictable behavior to do test driven development.
擬似エラーを起こすパラメータと同様に、?mock=trueと渡すことでmockデータが買えるように設計する
Warning: It's a good idea to only support the mock attribute on the test server and to raise an error if the mock parameter is included in production.
URLはよくデザインされたAPIにおいて最強のアフォーダンスだと考える
URLからfacadeパターンは輝き出す
backendのrequestの複雑さとは別に、userにはシンプルなfacadeとしてのURLを提供する
クライアント側が限られたhttp methodしか使えない場合、parameterでmethodを指定してもらうことで、backendへのリクエストはDELETEに変える
facade層を作ることでexternalのAPIやサービスの追加、変更が容易になる(ユーザはfacade層で提供されるものだけをみれば良いから)
domain server gateways sub-domain routing, versioning, firewalls caching
? オーケストレーション、トランスフォーメーション、コンプレッション、オーソライゼーション
CNAMEを使ってtest用、production用のsubdomainで分ける
test: api-test.hoge.com
production: api.hoge.com
the facade has a shunt that knows where the subdomain is and understands where to point - for example to the data stub server for test or to an internal system for production.
requestの種類(apiかapi-testかip addressか)によってそれらの処理を振り分ける機能(shunt)を持っている(data stubを返すのか、internal serverにつなぐのか)
versioning
最初のDNS,CNAMEで分けるのと同じ、facade内部でurlをパースして、internalの別サーバにつなぎにいく
facadeを経由せずのアクセスを防止するためにfirewallをinternalのシステムとfacadeの間に挟む
GeoDNS
処理を早くするために、requestのソースをGeoDNSが使って地理的に近いfacade(server)に振り分ける
orchestrate: 組織する、企てる
?
orchestration logic
Authorization
oauth
AuthDBを分ける(独自認証の場合)
API facadeパターンでよく言われるのが、facade パターンアプリケーション全体の複雑性を増すのではということだが、facadeパターンを使うにしろ使わないにしろ、app developerとAPIの間には切っても切り離せない複雑性が存在している。
これらの複雑祭は大抵個別のシステムによって覆い隠されており、特定することが難しい。 不明なものの上に複雑性を追加するのは良いことではない。facadeパターンは、他に方法がない時の選択を助ける????
http://www.infoq.com/jp/news/2014/01/api-orchestration-layer
http://www.infoq.com/jp/news/2013/02/netflix-api-optimization
APIサーバとユーザの間に一つ層を挟む(facade)
不特定多数に向けたAPIよりも、特定のdeviceなどに特化した形のAPIで使われることがおおい
全てのdeviceで同じAPIだと
Netflixのストリーミングサービスは800種類以降のデバイスで視聴できます。ほとんどのデバイスが私たちの非公開APIが提供するコンテンツを受け取ります。ひとつで全部のサイズに対応するAPIでこれら無数のデバイスをサポートするのは、上手くいってはいるものの、APIチームやUIチーム、そしてNetflixの顧客にとっては最適ではありません。
- RESTfulなAPIは最小公分母(最大規模における最低限)のソリューション。
- それぞれのエンドポイントがすべてのクライアントから利用されるので各デバイス向けのイノベーションが遅くなる。また、また機能開発はすべてデバイス向けに行わなければならない。
- APIチームがボトルネックになるので、イノベーションが遅くなる。顧客の要望は優先順位が付けられ対応の延期を余儀なくされる。
- ネットワークの通信回数は多く、ペイロードは不効率。
- 機能やデータタイプの有効無効を切り替える複雑なフラグがすべてのRESTfulエンドポイントに蔓延する。