La API Discovery proporciona una lista de APIs de Google para obtener metadatos de "documento de descubrimiento" legibles por máquina para cada API.
Este documento está dirigido a desarrolladores que quieran escribir bibliotecas de cliente, complementos de IDE y otras herramientas para interactuar con las APIs de Google.
Fondo del servicio de descubrimiento
Conceptos
El servicio de descubrimiento de las APIs de Google se basa en dos conceptos básicos:
- Directorio de APIs: una lista de todas las APIs compatibles con el servicio APIs Discovery. Cada entrada del directorio muestra información sobre una API compatible, como su nombre, una breve descripción de lo que hace y un enlace a la documentación. Una API puede tener varias entradas de directorio, una por cada una de sus versiones compatibles.
- Documento de descubrimiento: descripción legible por máquina de una API concreta. El documento de descubrimiento describe la superficie de una versión concreta de una API. En este documento se explica cómo acceder a los distintos métodos de cada API mediante llamadas HTTP RESTful. Un documento de Discovery incluye descripciones de los datos y los métodos asociados a la API, así como información sobre los ámbitos 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 Discovery de las APIs de Google funciona con dos tipos de recursos, según los conceptos anteriores.
Lista de APIs del directorio: una lista de APIs
Cada entrada de directorio contiene un par nombre/versión de la 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: iconos y un enlace a la documentación.
- Información de estado, incluidas las etiquetas de estado, y una indicación de si se trata o no de la versión preferida de la API.
-
Enlace al documento de descubrimiento: el URI del documento de descubrimiento de esta API (se indica como una URL completa; por ejemplo,
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Recurso de documento de descubrimiento: descripción legible por las máquinas de una API concreta
Además de la información proporcionada en el directorio de APIs, un documento de Discovery también incluye lo siguiente:
- Esquemas: se trata de 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 JSON Schema.
- Métodos: incluye una lista de métodos de la API y los parámetros disponibles para cada método.
- Permisos de OAuth: identifica la lista de permisos de OAuth disponibles para esta API.
- Documentación insertada, que proporciona descripciones breves de esquemas, métodos, parámetros y valores de parámetros disponibles.
La colección Directory es el contenedor conceptual del recurso Directory de la API y de los recursos Discovery Document de cada API admitida.
Operaciones
Puedes invocar dos métodos diferentes en colecciones y recursos del servicio Discovery de las APIs de Google, tal como se describe en la siguiente tabla.
| Operación | Descripción | Asignaciones HTTP de REST |
|---|---|---|
| lista | Muestra todas las APIs admitidas. | GET en el URI del recurso Directory. |
Estilos de llamada
REST
Las operaciones admitidas del servicio de descubrimiento de APIs de Google se asignan directamente al verbo HTTP REST GET, tal como se describe en Operaciones.
El formato específico para los URIs del servicio de descubrimiento de APIs de Google es:
https://API/$discovery/rest?version=VERSION
donde API es el identificador de un recurso de documento de descubrimiento y VERSION es el identificador de la versión concreta de la API.
A continuación, se muestran un par de ejemplos de cómo funciona en el servicio Discovery de las APIs de Google.
Lista de todas las APIs compatibles con el servicio Discovery 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 Service Usage, versión 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1