バージョニングの不適切なSOAPベースのAPIに長年悩まされていたeBayが、セマンティックバージョニングを備えたRESTful APIへの移行と非推奨標準(deprecation standard)の導入を決定した。今回の移行で重視されたのは、eBayのAPIを利用する新たなアプリケーションの開発を容易にする拡張性と適応性だ。Tanya Vlahovic氏がそのコンセプトと、それらがAPIにどのように実装されているかを説明している。
eBayのパブリックAPIアーキテクトリーダであるVlahovic氏にとって、APIはビジネスそのものだ。しかし氏は、個々のAPIは十分ではない、同時に使用することで初めてビジネスに真の価値をもたらすのだ、と強調する。氏はeBaysのAPIセットを、料理に例えて説明する — APIは材料であって、さまざまなAPIを新しい革新的な方法で組み合わせて、素晴らしい食事を考案するのは開発者コミュニティの役目なのだ。
柔軟で適応性の高いAPIエコシステムを確立するには、個々のAPIが成功したか失敗したかを理解することが重要になる。開発者によって使用されているか、あるいは、全く無視されているのか？APIが利用されるように改善するためには、APIのオーナは極めてオープンな態度で、さまざまな観点からソリューションを探す必要がある、とVlahovic氏は考えている。新しいAPIの例として氏が挙げるのは、"search by image"と"machine text translation"という、いずれも昨年夏にリリースされた２つである。
VlahovicはAPIを、3つの単純なことをするものとして説明する — アクションを実行してデータを収集し、データをフォーマットし、最後にそのデータを提供する。APIを開発する最も簡単な方法は、ドキュメントに必要以上の時間を費やさず、直感的で分かりやすいコントラクトをデザインして、開発者に試させてその価値を評価してもらうことだ、と氏は考えている。APIはロボットではなく、人間の開発者を対象としたインターフェースなのだ。
新たなRESTful APIでは、セマンティックバージョニングに従って、アルファ、ベータ、GA(一般公開)という3つの品質レベルが定義されている。これらのレベル以外に、実験的(experimental)なAPIもサポートする。これによってアーリーアダプタが、APIの調査やテストを行い、迅速なフィードバックを提供することが可能になる。
非推奨標準(deprecation standard)は、コントラクトとランタイム動作の両方に注目したもので、バージョニングで使用するものと同じ品質レベルに適用される。リソース、フィールド、あるいは動作など、APIの要素を非推奨にする場合、その要素は通常18か月間、そのままの形式で維持される。要素が新たに非推奨になる毎に、新しいマイナーバージョンのAPIがリリースされ、開発者への詳細なインストラクションを伴った公開アナウンスが提供される。インストラクションには、必要に応じて移行手順も含まれる。非推奨になることで下位互換性が絶たれる場合には、マイナーバージョンではなく新たなメジャーバージョンをリリースするかどうかを、APIのオーナが判断しなければならない。
APIの要素が非推奨になると、 非推奨属性がその要素に追加され、 description属性が非推奨を反映するように更新される。これら２つの属性は、OpenAPI仕様で定義されたものだ。実行時には、標準で定義されたWarning HTTP応答ヘッダとコード299を使用して、非推奨であることを通知する。コンシューマアプリケーションはこのヘッダを記録および監視して、新たに行われた変更をユーザに警告できなければならない。
Vlahovic氏はAPIを、開発者が新たなアプリケーションを開発するためのビルディングブロックであると考えている。この作業を簡略化するために、eBayでは、いくつかの概念を抽象化するSDKを提供している。その一例が、認証とデータプライバシ上の問題に対処するためにeBayが使用している、業界標準のOAuth 2.0プロトコルである。マーケットプレイス機能を使用するAPIクライアントは、すべて事前に承認されていなければならないため、このサポートはSDKに含まれている。既存のオープンソースJava OAuthクライアントライブラリに加えて、同社は先頃、C#およびPython用のライブラリバージョンをリリースした。
Vlahovic氏は以前にもブログ記事に、eBayがマーケットプレイス用に新たなAPIファミリを提供するために行った２年間の活動と、その中で氏らが学んだことについて記している。