Introducción
Este documento está dirigido a desarrolladores que desean escribir bibliotecas cliente, complementos IDE y otras herramientas para interactuar con las API de Google. El servicio de descubrimiento de API de Google te permite hacer todo lo anterior mediante la exposición de metadatos procesables sobre otras API de Google a través de una API simple. En esta guía, se proporciona una descripción general de cada sección del documento de descubrimiento, así como sugerencias útiles sobre cómo usarlo.
Todas las llamadas a la API son solicitudes REST no autenticadas y basadas en JSON que usan SSL, es decir, las URL comienzan con https.
Si no conoces los conceptos del servicio de descubrimiento de API de Google, consulta el artículo Primeros pasos antes de comenzar a programar.
Formato de documento discovery
En esta sección, se proporciona una descripción general del documento de descubrimiento.
En los siguientes ejemplos, se usa el documento de descubrimiento de la API de Google Cloud Service Management. Puedes cargar el documento de descubrimiento para la API de Google Cloud Service Management mediante la ejecución de esta solicitud GET:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1El formato de un documento discovery incluye información que se divide en seis categorías principales:
- Descripción básica de la API
- Authentication para la API.
- Detalles de esquema y recurso que describen los datos de la API.
- Detalles sobre los métodos de la API
- Información sobre las funciones personalizadas compatibles con la API
- Documentación intercalada que describe los elementos clave de la API
A continuación, se describe cada una de estas secciones de los documentos discovery. Consulta la documentación de referencia para obtener más detalles sobre cada propiedad.
Descripción básica de la API
El documento de descubrimiento contiene un conjunto de propiedades específicas de la API:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Estas propiedades a nivel de la API incluyen detalles sobre una versión particular de una API, como name, version, title y description. protocol siempre tiene un valor fijo de rest, ya que el servicio de descubrimiento de API solo admite métodos RESTful para acceder a las API.
El campo servicePath indica el prefijo de la ruta de acceso para esta versión de API en particular.
Autenticación
La sección auth contiene detalles sobre los alcances de autenticación de OAuth 2.0 para la API. Para obtener más información sobre cómo usar los permisos con OAuth 2.0, visita Usa OAuth 2.0 para acceder a las API de Google.
La sección auth contiene las secciones oauth2 y scopes anidadas. La sección scopes es una asignación de clave-valor del valor del permiso a más detalles sobre el alcance:
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
La sección auth solo define los alcances de una API en particular. Para obtener información sobre cómo se asocian estos alcances con un método de API, consulta la sección Métodos a continuación.
Recursos y esquemas
Las operaciones de una API actúan sobre objetos de datos llamados resources. El documento de descubrimiento se basa en el concepto de recursos. Cada documento de descubrimiento tiene una sección resources de nivel superior que agrupa todos los recursos asociados con la API. Por ejemplo, la API de Administración de servicios de Google Cloud tiene un recurso services y un recurso operations en el nivel superior resources, el recurso services tiene tres subrecursos, configs, rollouts y consumers:
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
Dentro de cada sección de recursos, se encuentran los métodos asociados con ese recurso. Por ejemplo, la API de Administración de servicios de Google Cloud tiene tres métodos asociados con el recurso services.rollouts: get, list y create.
Los esquemas indican cómo se ven los recursos en una API. Cada documento de descubrimiento tiene una sección schemas de nivel superior, que contiene un par nombre/valor de ID de esquema para el objeto. Los ID de esquema son únicos por API y se usan para identificar de forma única el esquema en la sección methods del documento de descubrimiento:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
El servicio de descubrimiento de API usa el esquema 03 de JSON para sus representaciones de esquema. A continuación, se muestra un fragmento del esquema JSON del recurso de URL, junto con un recurso de respuesta real:
| Esquema JSON del recurso de lanzamiento: | Respuesta de recurso de lanzamiento real: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
Los campos en negrita muestran la asignación entre el esquema JSON y la respuesta real.
Los esquemas también pueden contener referencias a otros esquemas. Si compilas una biblioteca cliente, esto puede ayudarte a modelar de manera eficaz los objetos de una API en tus clases de modelos de datos. En el ejemplo de Rollout anterior, la propiedad trafficPercentStrategy es en realidad una referencia a un esquema con el ID TrafficPercentStrategy. Si observas la sección schemas, encontrarás el esquema TrafficPercentStrategy. El valor de este esquema se puede sustituir por la propiedad trafficPercentStrategy en el recurso Rollout (ten en cuenta que la sintaxis $ref proviene de la especificación del esquema de JSON).
Los métodos también pueden hacer referencia a esquemas cuando indican sus cuerpos de solicitud y respuesta. Consulta la sección Métodos para obtener más información.
Métodos
El núcleo del documento de descubrimiento se basa en métodos. Los métodos son las operaciones que se pueden realizar en una API. Encontrarás la sección methods en varias áreas del documento de descubrimiento, incluso en el nivel superior (que denominamos métodos de nivel de API) o en el nivel resources.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
Si bien una API puede tener métodos a nivel de la API, un recurso debe tener una sección methods.
Cada sección methods es un mapa de clave-valor del nombre del método a otros detalles sobre ese método. En el siguiente ejemplo, se documentan tres métodos: get, list y create:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Por último, la sección de cada método detalla varias propiedades sobre ese método. Este es un ejemplo del método get:
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
En esta sección, se incluyen detalles generales del método, como un ID único para identificar el método, el httpMethod que se usará y el path del método (si quieres obtener detalles sobre cómo usar la propiedad path para calcular la URL completa del método, consulta la sección Cómo redactar una solicitud). Además de estas propiedades de métodos generales, existen algunas propiedades que conectan el método con otras secciones del documento de descubrimiento:
Permisos
La sección auth que se definió antes en esta documentación contiene información sobre todos los alcances que admite una API en particular. Si un método admite uno de estos alcances, tendrá un arreglo de alcances. Hay una entrada en este arreglo para cada alcance que admite el método. Por ejemplo, la sección scopes del método get de la API de Google Cloud Service Management se ve de la siguiente manera:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Ten en cuenta que elegir un alcance de autenticación para usar en tu aplicación depende de varios factores, como qué métodos se llaman y qué parámetros se envían junto con el método. Por lo tanto, el desarrollador es quien decide qué alcance usar. Discovery solo documenta qué alcances son válidos para un método.
Solicitud y respuesta
Si el método tiene un cuerpo de solicitud o respuesta, estos se documentan en las secciones request o response, respectivamente. En el ejemplo de get anterior, el método tiene un cuerpo response:
"response": {
"$ref": "Rollout"
}
La sintaxis anterior indica que el cuerpo de la respuesta está definido por un esquema JSON con un ID de Rollout. Este esquema se puede encontrar en la sección de esquemas de nivel superior. Los cuerpos de solicitud y respuesta usan la sintaxis $ref para hacer referencia a esquemas.
Parámetros
Si un método tiene parámetros que el usuario debe especificar, estos parámetros se documentan en la sección parameters a nivel del método. Esta sección contiene una asignación de clave-valor del nombre del parámetro para obtener más detalles sobre ese parámetro:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
En el ejemplo anterior, hay dos parámetros para el método get:serviceName y rolloutId. Los parámetros pueden ir en path o en la URL query; la propiedad location indica dónde debe colocar el parámetro la biblioteca cliente.
Hay muchas otras propiedades que describen el parámetro, incluidos los datos del parámetro type (útil para idiomas con tipos fuertes), si el parámetro es required y si el parámetro es una enumeración. Consulta la Guía de referencia para obtener más detalles sobre las propiedades.
Orden de los parámetros
Hay muchas formas en que las bibliotecas cliente pueden estructurar sus interfaces. Una forma es tener un método con cada parámetro de API en la firma del método. Sin embargo, como JSON es un formato sin orden, es difícil saber mediante programación cómo ordenar los parámetros en la firma del método. El arreglo parameterOrder proporciona un orden fijo de parámetros para realizar solicitudes. El arreglo enumera el nombre de cada parámetro en orden de importancia. Puede contener parámetros de ruta o de búsqueda, pero cada parámetro es obligatorio. En el ejemplo anterior, una firma de método Java podría verse de la siguiente manera:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);El primer valor del arreglo parameterOrder, serviceName, también es el primer elemento de la firma del método. Si había otros parámetros en el arreglo parameterOrder, irían después del parámetro serviceName. Como el array parameterOrder solo contiene los parámetros obligatorios, se recomienda incluir una forma para que los usuarios especifiquen parámetros opcionales. En el ejemplo anterior, se usa el mapa optionalParameters.
Carga de medios
Si un método admite la carga de contenido multimedia, como imágenes, audio o video, la ubicación y los protocolos compatibles para subir ese contenido multimedia se documentan en la sección mediaUpload. Esta sección contiene detalles sobre los protocolos de carga compatibles e información sobre los tipos de contenido multimedia que se pueden subir:
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
En el ejemplo anterior, la propiedad supportsMediaUpload es un valor booleano que determina si el método admite la carga de contenido multimedia. Si el valor es verdadero, la sección mediaUpload documenta los tipos de medios que se pueden subir.
La propiedad accept es una lista de rangos de medios que determinan los tipos de MIME que se pueden subir. El extremo que se muestra en el ejemplo anterior aceptará cualquier formato de imagen.
La propiedad maxSize tiene el tamaño máximo de una carga. El valor es una string en unidades de MB, GB o TB. En el ejemplo anterior, las cargas se limitan a un tamaño máximo de 10 MB. Ten en cuenta que este valor no refleja la cuota de almacenamiento restante de un usuario individual para esa API. Por lo tanto, incluso si la carga es menor que maxSize, la biblioteca cliente aún debe estar preparada para manejar una carga que falla por espacio insuficiente.
En la sección protocols, se enumeran los protocolos de carga que admite un método. El protocolo simple consiste simplemente en PUBLICAR el medio en el extremo determinado en una sola solicitud HTTP. El protocolo resumable implica que el extremo proporcionado en el URI path admite el protocolo de carga reanudable. Si la propiedad multipart es true, el extremo acepta las cargas multiparte, lo que significa que la solicitud JSON y el medio se pueden unir en un cuerpo mutuo/relacionado y enviarse juntos. Ten en cuenta que los protocolos simple y resumable pueden admitir cargas multiparte.
La propiedad path es una plantilla de URI y debe expandirse al igual que la propiedad path para el método, como se describe en la sección Cómo redactar una solicitud.
Descarga de contenido multimedia
Si un método admite la descarga de contenido multimedia, como imágenes, audio o video, esto se indica mediante el parámetro supportsMediaDownload:
"supportsMediaDownload": true,
Cuando descargas contenido multimedia, debes configurar el parámetro de búsqueda alt como media en la URL de la solicitud.
Si la propiedad useMediaDownloadService del método de la API es true, inserta /download antes de servicePath para evitar un redireccionamiento. Por ejemplo, la ruta de descarga es /download/youtube/v3/captions/{id} si la concatenación de servicePath y path es /youtube/v3/captions/{id}. Se recomienda crear una URL de descarga de contenido multimedia con /download, incluso si useMediaDownloadService es falso.
Parámetros comunes
El documento discovery de nivel superior contiene una propiedad parameters. Esta sección es similar a la sección de parámetros para cada método; sin embargo, estos parámetros se pueden aplicar a cualquier método en la API.
Por ejemplo, los métodos get, insert o list de la API de Google Cloud Service Management pueden tener un parámetro prettyPrint en los parámetros de la solicitud, lo que dará formato a la respuesta para todos esos métodos en un formato legible. A continuación, se muestra una lista de parámetros comunes:
| Parámetro | Significado | Notas | Aplicabilidad |
|---|---|---|---|
access_token |
Token de OAuth 2.0 para el usuario actual |
|
|
alt |
Formato de datos para la respuesta |
|
|
callback |
Función de devolución de llamada |
| |
fields |
Selector que especifica un subconjunto de campos para incluir en la respuesta |
|
|
key |
Clave de API (OBLIGATORIA*) |
|
|
prettyPrint |
Muestra una respuesta con identificaciones y saltos de línea. |
|
|
quotaUser |
Alternativa a userIp. |
|
|
userIp |
Dirección IP del usuario final para el cual se realiza la invocación de la API. |
|
Funciones
Hay algunos casos en los que las API admiten funciones personalizadas fuera del alcance del resto del documento de descubrimiento. Estos se recopilan en el arreglo features. El arreglo de atributos contiene una etiqueta de string para cada función especial que admite la API. Actualmente, dataWrapper es la única función compatible, pero es posible que se admitan otras funciones en el futuro.
"features": dataWrapper
La función dataWrapper indica que todas las solicitudes y respuestas de la API se encuentran dentro de un objeto data JSON. Esta es una función de las API de Google anteriores, pero dejará de estar disponible en el futuro. Las siguientes API admiten la función dataWrapper: Moderador v1 y Traductor v2.
Si eres un desarrollador de bibliotecas cliente, si una API admite la función &data:
- En solicitudes: une el recurso de solicitud en un objeto JSON
data. - En respuestas: Busca el recurso dentro de un objeto JSON
data.
Los esquemas del documento de descubrimiento no contienen el wrapper de datos, por lo que debe agregarlos y quitarlos de manera explícita. Por ejemplo, supongamos que hay una API con un recurso llamado &Foot" que se ve de la siguiente manera:
{
"id": 1,
"foo": "bar"
}
Antes de insertar este recurso mediante la API, debes unirlo a un elemento de datos:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Por otro lado, cuando obtienes una respuesta de la API, también contiene el wrapper de datos:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Para obtener el recurso definido por el esquema, debes quitar el wrapper de datos:
{
"id": 1,
"foo": "bar"
}
Documentación intercalada
Cada documento de descubrimiento tiene anotaciones con varios campos description que proporcionan documentación intercalada para la API. Los campos description se pueden encontrar para los siguientes elementos de la API:
- API en sí
- Alcances de OAuth
- Esquemas de recursos
- Métodos de la API
- Parámetros del método
- Valores aceptables para ciertos parámetros
Estos campos son especialmente útiles si deseas usar el servicio de descubrimiento de API de Google a fin de generar documentación en lenguaje natural para una biblioteca cliente, por ejemplo, JavaDoc.