La API de Discovery proporciona una lista de las APIs de Google con el objetivo de recuperar metadatos de “documento de descubrimiento” procesables para cada API.
Este documento está dirigido a desarrolladores que deseen escribir bibliotecas cliente, complementos de IDE y otras herramientas para interactuar con las APIs de Google.
Información general del servicio de descubrimiento
Conceptos
El servicio de descubrimiento de las APIs de Google se basa en dos conceptos básicos:
- Directorio de las APIs: Una lista de todas las APIs compatibles con el Servicio de descubrimiento de las APIs. Cada entrada del directorio muestra detalles sobre una API compatible, incluido su nombre, una breve descripción de lo que hace y un vínculo de documentación. Una API puede tener varias entradas de directorio, una para cada una de sus versiones compatibles.
- Documento de descubrimiento: Una descripción procesable de una API en particular. El Documento de descubrimiento describe la superficie de una versión particular de una API. En el documento, se proporciona información detallada sobre cómo acceder a los distintos métodos de cada API a través de llamadas HTTP RESTful. Un documento de descubrimiento incluye descripciones de los datos y métodos asociados con la API, así como información sobre los permisos de OAuth disponibles y descripciones de esquemas, métodos, parámetros y valores de parámetros disponibles.
Modelo de datos
Un recurso es una entidad de datos individual con un identificador único. El servicio de descubrimiento de las APIs de Google funciona en dos tipos de recursos, según los conceptos anteriores.
Lista de directorios de las APIs: Una lista de las APIs
Cada entrada del directorio contiene un par nombre/versión de API con la siguiente información:
- Información de identificación y descripción,: nombre, versión, título y descripción.
- Información de la documentación: íconos y un vínculo de documentación.
- Información de estado, incluidas las etiquetas de estado y una indicación de si esta es la versión preferida de la API o no.
-
Vínculo del documento de descubrimiento, el URI del documento de descubrimiento para esta API
(proporcionado como una URL completa, por ejemplo,
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Recurso de Documento de descubrimiento: Una descripción procesable de una API en particular
Además de la información que se proporciona en el directorio de las APIs, un documento de descubrimiento también incluye lo siguiente:
- Esquemas, que es una lista de esquemas de recursos de la API que describen los datos a los que tienes acceso en cada API. Los esquemas del servicio de descubrimiento de las APIs de Google se basan en el esquema JSON.
- Métodos, que incluye una lista de métodos de API y parámetros disponibles para cada método.
- Permiso de OAuth, que identifica la lista de permisos de OAuth disponibles para esta API.
- Documentación intercalada, que proporciona descripciones breves de esquemas, métodos, parámetros y valores de parámetros disponibles.
La única colección de directorio es el contenedor conceptual del único recurso de directorio de las APIs y los recursos de documento de descubrimiento para cada API compatible.
Operaciones
Puedes invocar dos métodos diferentes en las colecciones y los recursos del Servicio de descubrimiento de las APIs de Google, como se describe en la siguiente tabla.
| Operación | Descripción | Asignaciones de HTTP de REST |
|---|---|---|
| lista | Enumera todas las APIs compatibles. | GET en el URI de recurso del directorio. |
Estilo de la llamada
REST
Las operaciones del servicio de descubrimiento de las APIs de Google admitidas se asignan directamente al verbo HTTP GET de REST,
como se describe en Operaciones.
El formato específico para los URI del servicio de descubrimiento de las APIs de Google es el siguiente:
https://API/$discovery/rest?version=VERSION
en el que API es el identificador de un recurso de documento de descubrimiento y VERSION es el identificador de la versión particular de la API.
Estos son algunos ejemplos de cómo funciona esto en el servicio de descubrimiento de las APIs de Google.
Enumera todas las APIs compatibles con el servicio de descubrimiento de las APIs de Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Pruébalo ahora en el Explorador de APIs.
Obtén el documento de descubrimiento de la API de Service Usage, versión 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1