API設計は基本的に、誰がそのAPIを利用するのか、どのように使うのかを知っているかどうかに依存する。Netflix APIのエンジニアリングディレクターであるDaniel Jacobson氏はThe Next Webの記事でこのように語っている。これは当たり前のように思えるかもしれないが、Daniel氏は次のように続ける。従来の「フリーサイズ（one-size-fits-all）」のリソース指向APIは、API利用者にとって最も大事なことを満たせていないかもしれない。良いAPI設計とは、単に「リソースモデリング、ペイロードフォーマット、システムのバージョン付け方法、セキュリティ」の話だけではない。もっと基本的な問いは「だれがこのAPIの一番の利用者であり、彼らのためにAPIをどのように最適化できるか？」だ。
リソース指向APIは「よく知らない大多数の開発者」に対して機能するかもしれないが、実際のところ、多くの組織は特定のユースケースを持った「既知の少数の開発者」のニーズに取り組んでいる。「それは、APIチームやiPhoneアプリを開発するために雇った委託会社、協力会社のエンジニアリングチームから来た、廊下の先にいるエンジニアかもしれません」とDaniel氏は言う。この場合、APIを最適化するチャンスがある。
アーキテクチャにAPIオーケストレーション層を導入するところが増えている。Daniel氏はこの層を「汎用にモデル化されたデータ要素や機能を利用して、ターゲットとする開発者やアプリケーション向けに、より具体的な手段を提供する抽象化層」と定義している。 Daniel氏はオーケストレーション層の基本原則として以下を挙げている。
- APIプロバイダが提供するAPIの多くは、データモデルの純度を保つよう定義されています。オーケストレーション層を構築するときには、時として最適化やパフォーマンスに有利となる純度をあきらめなくてはならないことを覚悟しましょう。
- APIチームが提供するAPIの多くは、APIチームにとってサポートしやすいよう定義されています。オーケストレーション層を構築するときには、APIチームにとって複雑になることを覚悟しましょう。
- API利用者が多岐にわたることを理解することは重要です。必要なのはオーケストレーション層だけかもしれませんし、オーケストレーション層に加えてフリーサイズのAPIも必要かもしれません。
2番目の原則は「スマートな」ビデオレコーダーのためのインターフェイス設計とよく似ている。ボックスの外側にいるユーザに楽をさせるため、ボックスの内側は複雑になってくるのだ。
Daniel氏は、最後にオーケストレーション層のよくある3つのユースケース、デバイス固有ラッパー、クエリベースAPIのサポート、エクスペリエンスベースAPIの提供について説明した。彼はデバイス固有のラッパーが一番よく見かけるユースケースだと述べて、iPhone向けに最適化したAPIラッパーの例を挙げた。デバイス固有ラッパーは通常、APIチームによって特定の利用者向けに提供される。これに対して、クエリベースAPIは、API利用者が自分で「柔軟なパラメータとペイロードを通してデータベースのように（リソースに対して）問い合わせる」ことを可能にする。
エクスペリエンスベースAPIはNetflixが採用しているモデルであり、先ほどの2つのユースケースを組み合わせて、API利用者がデバイス固有ラッパーを設計、実装、所有するというものだ。APIチームが汎用で再利用可能な形でデータを提供し、API利用者がデータのフォーマットと配信を所有する、という責務境界になる。
Daniel氏は、APIチームはAPI利用者を協力すべき設計パートナーとして見なす必要がある、それによってエンドユーザは望み得る最高のエクスペリエンスを得ることができる、と結論づけている。