Discovery API の概要

Discovery API は、各 API の機械判読可能なディスカバリ ドキュメントのメタデータを取得するための Google API のリストを提供します。

このドキュメントは、Google API とやり取りするためのクライアント ライブラリ、IDE プラグイン、その他のツールを作成するデベロッパーを対象としています。

Discovery Service の背景

コンセプト

Google APIs Discovery Service は、次の 2 つの基本コンセプトに基づいて構築されています。

  • API ディレクトリ: APIs Discovery Service でサポートされているすべての API のリスト。各ディレクトリ エントリには、サポートされている API の詳細（名前、機能の簡単な説明、ドキュメントのリンクなど）が表示されます。API には複数のディレクトリ エントリを設定できます（サポートされているバージョンごとに 1 つずつ）。
  • ディスカバリ ドキュメント: 特定の API に関する機械判読可能な説明。ディスカバリ ドキュメントには、API の特定のバージョンのサーフェスが記述されています。このドキュメントでは、RESTful HTTP 呼び出しを介して各 API のさまざまなメソッドにアクセスする方法について説明します。ディスカバリ ドキュメントには、API に関連付けられたデータとメソッドの説明、使用可能な OAuth スコープに関する情報、スキーマ、メソッド、パラメータ、使用可能なパラメータ値の説明が記述されています。

データモデル

リソースとは、固有識別子を持つ個別のデータ エンティティです。Google APIs Discovery Service は、前述のコンセプトに基づいて 2 種類のリソースを使用します。

API ディレクトリ リスト: API のリスト

各ディレクトリ エントリには、API の名前とバージョンのペアが含まれています。このエントリには、次の情報も含まれています。

  • 識別と説明の情報: 名前、バージョン、タイトル、説明。
  • ドキュメントの情報: アイコンとドキュメントへのリンク。
  • ステータスの情報: ステータス ラベルと、これが API の優先バージョンかどうかの表示。
  • ディスカバリ ドキュメントのリンク。この API のディスカバリ ドキュメントの URI（完全な URL）。例: https://serviceusage.googleapis.com/$discovery/rest?version=v1。

ディスカバリ ドキュメント リソース: 特定の API を機械で読み取れる形式で記述したリソース。

ディスカバリ ドキュメントには、API ディレクトリに記述されている情報に加えて、次の情報が含まれています。

  • スキーマ。各 API でアクセスできるデータを記述する API リソース スキーマのリスト。Google APIs Discovery Service のスキーマは JSON スキーマに基づいています。
  • メソッド。API メソッドのリストと、各メソッドで使用可能なパラメータを含みます。
  • OAuth スコープ。この API で使用可能な OAuth スコープのリストを示します。
  • インライン ドキュメント。スキーマ、メソッド、パラメータ、使用可能なパラメータ値の簡単な説明が記述されています。

単一のディレクトリ コレクションは、単一の API ディレクトリ リソースと、サポートされている各 API のディスカバリ ドキュメント リソースを含む概念的なコンテナです。

オペレーション

次の表に示すように、Google APIs Discovery Service では、コレクションとリソースに対して 2 つの異なるメソッドを呼び出すことができます。

オペレーション 説明 REST HTTP マッピング
list サポートされているすべての API のリストを返します。 ディレクトリ リソース URI の GET。

呼び出しのスタイル

REST

オペレーションで説明されているように、サポートされている Google APIs Discovery Service オペレーションは REST HTTP GET 動詞に直接マッピングされます。

Google API Discovery Service の URI の形式は次のとおりです。

https://API/$discovery/rest?version=VERSION

ここで、API はディスカバリ ドキュメント リソースの識別子、VERSION は API の特定のバージョンの識別子です。

以下に、Google APIs Discovery Service での動作を示す例をいくつか示します。

Google API Discovery Service でサポートされているすべての API のリストを返します。

GET https://discovery.googleapis.com/discovery/v1/apis

API Explorer で今すぐお試しください

Service Usage API バージョン 1 のディスカバリ ドキュメントを取得します。

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1