A API Discovery fornece uma lista de APIs Google para obter metadados de "documento de descoberta" legíveis por máquina para cada API.
Este documento destina-se a programadores que querem escrever bibliotecas de clientes, plug-ins de IDEs e outras ferramentas para interagir com as APIs Google.
Contexto do serviço de descoberta
Conceitos
O serviço Google APIs Discovery baseia-se em dois conceitos básicos:
- Diretório de APIs: uma lista de todas as APIs suportadas pelo serviço de deteção de APIs. Cada entrada do diretório mostra detalhes sobre uma API suportada, incluindo o respetivo nome, uma breve descrição do que faz e um link para a documentação. Uma API pode ter várias entradas no diretório, uma para cada uma das respetivas versões suportadas.
- 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 aceder aos vários métodos de cada API através de chamadas HTTP RESTful. Um documento de descoberta inclui descrições dos dados e métodos associados à API, bem como informações sobre os âmbitos 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 de dados individual com um identificador exclusivo. O serviço Google APIs Discovery funciona com dois tipos de recursos, com base nos conceitos acima.
Lista do diretório de APIs: uma lista de APIs
Cada entrada de diretório contém um par 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 estado, incluindo etiquetas de estado e uma indicação sobre se esta é ou não a versão preferencial da API.
-
Link do documento de deteção, o URI do documento de deteção para esta API
(indicado como um URL completo, por exemplo,
https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Recurso de 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:
- Esquemas, que é uma lista de esquemas de recursos de API que descrevem os dados aos quais tem acesso em cada API. Os esquemas do serviço Google APIs Discovery baseiam-se no esquema JSON.
- Métodos, incluindo uma lista de métodos da API e parâmetros disponíveis para cada método.
- Âmbitos do OAuth, que identifica a lista de âmbitos do OAuth disponíveis para esta API.
- Documentação inline, que fornece breves descrições de esquemas, métodos, parâmetros e valores de parâmetros disponíveis.
A única coleção de diretórios é o contentor conceptual do único recurso do diretório de APIs e dos recursos do documento Discovery para cada API suportada.
Operações
Pode invocar dois métodos diferentes em coleções e recursos no serviço Google APIs Discovery, conforme descrito na tabela seguinte.
| Operação | Descrição | Mapeamentos HTTP REST |
|---|---|---|
| list | Apresenta todas as APIs suportadas. | GET no URI do recurso Directory. |
Estilo de chamadas
REST
As operações do serviço Google APIs Discovery suportadas são mapeadas diretamente para o verbo HTTP REST, conforme descrito em Operações.GET
O formato específico dos URIs do serviço Google APIs Discovery é:
https://API/$discovery/rest?version=VERSION
onde API é o identificador de um recurso de documento de descoberta e VERSION é o identificador da versão específica da API.
Seguem-se alguns exemplos de como isto funciona no serviço Google APIs Discovery.
Indique todas as APIs suportadas pelo serviço Google APIs Discovery:
GET https://discovery.googleapis.com/discovery/v1/apis
Experimente já no Explorador de APIs!
Obtenha o documento Discovery para a API Service Usage, versão 1:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1