APIs.jsonはドメインのAPIを公開して,検索エンジンによる検出を可能にする。
APIs.jsonとは,ドメインがAPI情報を公開するためのAPI定義フォーマットであり,それを記述したファイルの名称である。ドメインのルートに配置されるファイルに,マシン可読な形式のAPI定義と,関連するファイルへのリンクを記述する。検索エンジンがWebサイトのコンテントをインデックスする時に使用するrobot.txtのような方法で,API発見とインデックスのための情報を提供するものだ。
APIs.jsonはまだバージョン0.14だが,作者によると "仕様としてはすでに完成"していて,"コミュニティで今すぐにでも導入可能な状態"である。フォーマットには,必須あるいは省略可能な要素が数多く定義されている。その中のいくつかを引用すると,
- Name [必須]: 人が読める形式の,APIコレクションの名称のテキスト文字列。
- Description [必須]: 人が読める形式の,APIコレクションの説明テキスト文字列。
- Created [必須]: ファイルの生成日付。
- Apis (コレクション) [オプション]: ファイル内で識別される APIのリストで,それぞれ次の内容を含む:
Name [必須]: APIの名称。
Description [必須]: 人が読める形式のAPI説明テキスト。
baseUrl: APIあるいは一次エンドポイントのルートにあたるWebのURL。
Version [オプション]: 対象とするAPIのバージョン番号を表す文字列。
プロパティ (コレクション):
- type: 下記の予約語を参照。
- url または値。
APIs.jsonは,3Scale(Steve Willmott -@njyx, Nicolas Grenie -@picsoung)とAPI Evangelist(Kin Lane -@kinlane)が協力した,共同作業の成果である。InfoQはこのプロジェクトについてより詳しく知るため,Kin Lane氏にインタビューした。
InfoQ: このフォーマットを標準化団体に提出する予定はありますか?
KL: 標準化団体への提出は,将来的な選択肢のひとつですね。現在はフォーマットに対して,可能な限り多くのフィードバックを集める作業をしています。数千のドメインに展開して完成度を高めた上で,次のステップについて検討する予定です。
InfoQ: 実際にフォーマットを使用しているWebサイトはありますか?
KL: apievangelist.comが最初で,現在は98のプロバイダで138のAPIが公開されています。ただし,その多くは公式プロバイダではなく,外部の第3者が提供しているものですが,SpotifyやDiffbot, Paypal, MYOB, Neutrino APIなどのプロバイダが提供する公式のAPIs.jsonも多数あります。
InfoQ: "コミュニティですぐにでも導入可能な状態"と考えているにも関わらず,現在のバージョンが0.14とマークされているのはなぜですか? v1.0にするべきではないでしょうか?
KL: バージョン.11から始めて,フィードバックやさまざまなイベントを繰り返しているうちに,いつの間にか.14まで達してしまいました。何百というプロバイダに認められて,広く利用されてはいますが,1.0バージョンにするのはまだ適切ではないと思っています。これまでに何ヶ月も費やして現在の位置に到達しましたが,まだやるべきことが数多くあります。
InfoQ: APIs.jsonはSwaggerやRAML, Blueprint, WADL, WSDLといったAPIフォーマットをサポートしています。今後さらにサポート対象を増やす予定はありますか?
KL: ローンチ時点では,主流のAPI定義フォーマットのサポートに注力していました。ただし,APIプロパティを使用すれば,どのようなAPI定義フォーマットでも指定することができます。制限は何もありません。特定の定義が広く普及するようであれば,コアスペックにそれを採用するつもりです。
InfoQ: 短期的あるいは長期的には,どのような計画があるのでしょう?
KL: ひたすら実装を続けるのみですね。APIプロバイダにAPIs.jsonを紹介して,その実装を支援しています。また公開検索用だけではなく,内部的に使用することのメリットを理解してもらうことも必要でしょう。それと同時に,APIs.jsonのメリットを皆に知ってもらうために,オープンソースの検索エンジンであるAPIs.ioなどの支援ツールの開発も続けていくつもりです。
APIs.jsonにはオープンソースの検索エンジンであるAPIs.ioが付属する。Webをクロールした結果をapis.jsonファイルにインデックスすることが可能だ。Webサイトでは,apis.jsonファイルへの新たなAPIの登録や生成,検証を行うツールも多数公開されている。
APIs.jsonプロジェクト全体はMITライセンスの下,GitHubでオープンソースとして提供される。