Discovery API предоставляет список API Google для извлечения машиночитаемых метаданных «Документа Discovery» для каждого API.
Этот документ предназначен для разработчиков, желающих писать клиентские библиотеки, плагины IDE и другие инструменты для взаимодействия с API Google.
История службы обнаружения
Концепции
Служба обнаружения API Google построена на двух основных концепциях:
- Каталог API : список всех API, поддерживаемых службой обнаружения API. Каждая запись каталога содержит подробную информацию о поддерживаемом API, включая его имя , краткое описание функций и ссылку на документацию . API может иметь несколько записей каталога, по одной для каждой поддерживаемой версии.
- Документ Discovery : машиночитаемое описание конкретного API. Документ Discovery описывает внешний вид конкретной версии API. В документе подробно описывается, как получить доступ к различным методам каждого API посредством HTTP-вызовов RESTful. Документ Discovery включает описания данных и методов, связанных с API, а также информацию о доступных областях действия OAuth, а также описания схем, методов, параметров и доступных значений параметров.
Модель данных
Ресурс — это отдельный объект данных с уникальным идентификатором. Служба обнаружения API Google работает с двумя типами ресурсов, основываясь на вышеизложенных концепциях.
Список каталогов API: список API
Каждая запись каталога содержит пару имя / версия API со следующей информацией:
- Идентификационная и описательная информация : имя, версия, заголовок и описание.
- Информация о документации : значки и ссылка на документацию.
- Информация о статусе , включая метки статуса и указание на то, является ли эта версия API предпочтительной.
- Ссылка на документ обнаружения — URI документа обнаружения для этого API (указывается как полный URL, например,
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Ресурс Discovery Document: машиночитаемое описание конкретного API
Помимо информации, представленной в Справочнике API, документ Discovery также включает:
- Схемы — это список схем ресурсов API, описывающих данные, к которым у вас есть доступ в каждом API; схемы службы обнаружения API Google основаны на схеме JSON .
- Методы , включая список методов API и доступных параметров для каждого метода.
- Области действия OAuth , которые определяют список областей действия OAuth, доступных для этого API.
- Встроенная документация , которая содержит краткие описания схем, методов, параметров и доступных значений параметров.
Единая коллекция каталогов представляет собой концептуальный контейнер единого ресурса каталога API и ресурсов Discovery Document для каждого поддерживаемого API.
Операции
Вы можете вызвать два различных метода для коллекций и ресурсов в службе обнаружения API Google, как описано в следующей таблице.
| Операция | Описание | Сопоставления REST HTTP |
|---|---|---|
| список | Список всех поддерживаемых API. | GET по URI ресурса каталога. |
Стиль вызова
ОТДЫХ
Поддерживаемые операции службы обнаружения API Google напрямую сопоставляются с командой REST HTTP GET , как описано в разделе «Операции» .
Конкретный формат URI службы обнаружения API Google:
https://API/$discovery/rest?version=VERSION
где API — идентификатор ресурса Discovery Document, а VERSION — идентификатор конкретной версии API.
Вот несколько примеров того, как это работает в службе обнаружения API Google.
Перечислите все поддерживаемые API службы обнаружения API Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Попробуйте прямо сейчас в API Explorer!
Получите документ Discovery для API использования услуг, версия 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1