A API Discovery fornece uma lista de APIs do Google para recuperar metadados de documentos e "documentos que podem ser lidos por máquina para cada API.
Este documento é destinado a desenvolvedores que querem criar bibliotecas de clientes, plug-ins de ambiente de desenvolvimento integrado e outras ferramentas para interagir com as APIs do Google.
Contexto do serviço de descoberta
conceitos
O serviço de descoberta de APIs do Google foi criado com base em dois conceitos básicos:
- Diretório de APIs: uma lista de todas as APIs compatíveis com o serviço de descoberta de APIs. Cada entrada do diretório mostra detalhes sobre uma API compatível, incluindo o nome, uma breve descrição do que ela faz e um link de documentação. Uma API pode ter várias entradas do diretório, uma para cada versão compatível.
- Documento de descoberta: uma descrição legível por máquina de uma API específica. O documento Discovery descreve a superfície de uma versão específica de uma API. O documento fornece detalhes sobre como acessar os vários métodos de cada API usando chamadas HTTP RESTful. Um documento de descoberta inclui descrições dos dados e métodos associados à API, bem como informações sobre os escopos OAuth disponíveis e descrições de esquemas, métodos, parâmetros e valores de parâmetros disponíveis.
Modelo de dados
Um recurso é uma entidade individual de dados com um identificador exclusivo. O serviço de descoberta de APIs do Google opera em dois tipos de recursos, com base nos conceitos acima.
APIs Directory List: uma lista de APIs.
Cada entrada do diretório contém um par de nome/versão da API com as seguintes informações:
- Informações de identificação e descrição: nome, versão, título e descrição.
- Informações da documentação: ícones e um link para a documentação.
- Informações de status, incluindo rótulos de status e uma indicação de que essa é a versão preferencial da API ou não.
- Link do documento de descoberta, o URI do documento de descoberta para essa API (fornecido como um URL completo, por exemplo, https://servicemanagement.googleapis.com/$discovery/rest?version=v1).
Recurso do documento de descoberta: uma descrição legível por máquina de uma API específica.
Além das informações fornecidas no diretório de APIs, um documento Discovery também inclui o seguinte:
- Esquemas, que é uma lista de esquemas de recursos de API que descrevem os dados a que você tem acesso em cada API, e são baseados nos esquema JSON.
- Métodos, incluindo uma lista de métodos de API e parâmetros disponíveis para cada método.
- Escopos do OAuth, que identifica a lista de escopos do OAuth disponíveis para essa API.
- Documentação in-line, que fornece uma breve descrição dos esquemas, métodos, parâmetros e valores de parâmetros disponíveis.
A única coleção de diretórios é o contêiner conceitual do recurso único de diretório de APIs e os recursos de documentos do Discovery para cada API compatível.
Veja mais detalhes sobre os recursos do diretório de APIs e o recurso de documento do Discovery nos documentos Como usar a API e Referência.
Operações
É possível invocar dois métodos diferentes em coleções e recursos no serviço de descoberta de APIs do Google, conforme descrito na tabela a seguir.
| Operação | Descrição | Mapeamentos HTTP REST |
|---|---|---|
| list | Lista todas as APIs compatíveis. | GET no URI do recurso de diretório. |
Estilo da chamada
REST
As operações do serviço Discovery de APIs do Google compatíveis são mapeadas diretamente para o verbo HTTP GET REST, conforme descrito em Operações.
O formato específico dos URIs do serviço Discovery de APIs do Google é:
https://discovery.googleapis.com/discovery/v1/apis?parameters
em que api é o identificador de um recurso de documento de descoberta, e version é o identificador da versão específica da API, e _parameters_ são os parâmetros que se aplicam à consulta. Consulte o resumo do parâmetro de consulta na documentação de referência para mais detalhes.
Veja detalhes sobre o conjunto completo de URIs usados em cada operação compatível na API no documento Referência das serviços Discovery do Google APIs.
Estes são alguns exemplos de como isso funciona no serviço de descoberta de APIs do Google.
Liste todas as APIs compatíveis com o serviço das APIs do Google Discovery:
GET https://discovery.googleapis.com/discovery/v1/apis
Acesse o documento de descoberta da API Google Cloud Service Management, versão 1:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1