La API de Discovery proporciona una lista de las API de Google a fin de recuperar los metadatos de un documento de descubrimiento que se puede leer automáticamente para cada API.
Este documento está dirigido a desarrolladores que desean escribir bibliotecas cliente, complementos IDE y otras herramientas para interactuar con las API de Google.
Antecedentes del servicio de descubrimiento
Conceptos
El servicio de descubrimiento de API de Google se basa en dos conceptos básicos:
- Directorio de API: Una lista de todas las API que admite el Servicio de descubrimiento de API. Cada entrada del directorio muestra detalles sobre una API compatible, incluido su name, una breve descripción de lo que hace y un vínculo de documentación. Una API puede tener varias entradas del directorio, una para cada una de sus versiones compatibles.
- Documento de descubrimiento: Una descripción legible de una API en particular. El documento de descubrimiento describe la superficie para una versión particular de una API. En el documento se proporcionan detalles 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 alcances 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 API de Google opera en dos tipos de recursos, según los conceptos anteriores.
Lista de directorios de API: Una lista de API
Cada entrada del directorio contiene un par name/version 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 para confirmar si se trata de 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, p.ej., https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
Recurso de Documento de descubrimiento: Una descripción legible de una API en particular
Además de la información proporcionada en el Directorio de API, un documento de descubrimiento también incluye lo siguiente:
- Esquemas, que es una lista de esquemas de recursos de API que describen los datos a los que tienes acceso en cada API. Los esquemas de servicio de descubrimiento de API de Google se basan en el esquema JSON.
- Métodos, incluida una lista de métodos de API y parámetros disponibles para cada método
- Alcances de OAuth, que identifican la lista de alcances 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 colección de directorios única es el contenedor conceptual del recurso de directorio de API único y los recursos de documentos de descubrimiento para cada API compatible.
Se proporcionan más detalles sobre el recurso del Directorio de API y el recurso de Documento de descubrimiento en los documentos Usar la API y Referencia.
Operaciones
Puedes invocar dos métodos diferentes en colecciones y recursos en el servicio de descubrimiento de API de Google, como se describe en la siguiente tabla.
| Operación | Descripción | Asignaciones HTTP de REST |
|---|---|---|
| list | Enumera todas las API compatibles. | GET en el URI del recurso de directorio |
Estilo de llamada
REST
Las operaciones admitidas del servicio de descubrimiento de API de Google se asignan directamente al verbo HTTP REST GET, como se describe en Operaciones.
El formato específico de los URI del servicio de descubrimiento de las API de Google es el siguiente:
https://discovery.googleapis.com/discovery/v1/apis?parameters
En el ejemplo anterior, api es el identificador de un recurso de Documento de descubrimiento, y version es el identificador de la versión particular de la API, y _parameters_ son parámetros que se deben aplicar a la consulta. Consulta el resumen de parámetros de consulta en la documentación de referencia para obtener más detalles.
Los detalles sobre el conjunto completo de URI utilizados para cada operación compatible en la API se resumen en el documento Referencia de servicios de descubrimiento de API de Google.
Estos son algunos ejemplos de cómo funciona esto en el servicio de descubrimiento de API de Google.
Enumera todas las API admitidas por el servicio de descubrimiento de API de Google:
GET https://discovery.googleapis.com/discovery/v1/apis
Pruébalo ahora en el Explorador de API
Obtén el documento de descubrimiento para la API de Google Cloud Service Management, versión 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1