Uso da API

Introdução

Este documento é destinado a desenvolvedores que querem escrever bibliotecas de clientes, plug-ins de ambiente de desenvolvimento integrado e outras ferramentas para interagir com as APIs do Google. Com o serviço de descoberta de APIs do Google, você pode fazer tudo isso com a exposição de metadados legíveis por máquina sobre outras APIs do Google por meio de uma API simples. Este guia oferece uma visão geral de cada seção do documento de descoberta, além de dicas úteis sobre como usar o documento.

Todas as chamadas para a API são solicitações REST não baseadas em JSON e que usam SSL, ou seja, os URLs começam com https.

Se você não conhece os conceitos do serviço de descoberta de APIs do Google, leia os Primeiros passos antes de começar a programar.

Formato de documento do Discovery

Nesta seção, apresentamos uma visão geral do documento de descoberta.

Todos os exemplos abaixo usam o documento Discovery da API Google Cloud Service Management. Carregue o documento de descoberta da API Google Cloud Service Management executando esta solicitação GET:

GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1

O formato de um documento Discovery inclui informações que se enquadram em seis categorias principais:

• Descrição básica da API
• Informações de autenticação da API.
• Detalhes do recurso e do esquema que descrevem os dados da API.
• Detalhes sobre os métodos da API
• São informações sobre quaisquer recursos compatíveis com a API.
• Documentação in-line que descreve os principais elementos da API.

Cada uma dessas seções do documento de descoberta será descrita abaixo. Consulte a documentação Referência para mais detalhes sobre cada propriedade.

Descrição básica da API

O documento do Discovery contém um conjunto de propriedades específicas da 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": "",

Essas propriedades no nível da API incluem detalhes sobre uma versão específica de uma API, incluindo name, version, title e description. O protocol sempre tem um valor fixo de rest, já que o serviço de descoberta de APIs só é compatível com métodos RESTful de acesso às APIs.

O campo servicePath indica o prefixo do caminho para esta versão específica da API.

Autenticação

A seção auth contém detalhes sobre os escopos de autenticação do OAuth 2.0 para a API. Para saber mais sobre como usar escopos com o OAuth 2.0, acesse Como usar o OAuth 2.0 para acessar as APIs do Google.

A seção auth contém uma seção aninhada oauth2 e scopes. A seção scopes é um mapeamento de chave-valor do valor do escopo para mais detalhes sobre o escopo:

"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"
      }
    }
  }
}

A seção auth define apenas os escopos de uma API específica. Para saber como esses escopos são associados a um método de API, consulte a seção Métodos abaixo.

Recursos e esquemas

As operações de uma API agem em objetos de dados chamados resources. O documento Discovery foi criado com base no conceito de recursos. Cada documento Discovery tem uma seção resources de nível superior que agrupa todos os recursos associados à API. Por exemplo, a API Google Cloud Service Management tem um recurso services e um recurso operations no resources de nível superior, o recurso services tem três sub-recursos, configs, rollouts e 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 seção de recursos estão os métodos associados a esse recurso. Por exemplo, a API Google Cloud Service Management tem três métodos associados ao recurso services.rollouts: get, list e create.

Os esquemas informam como são os recursos em uma API. Cada documento Discovery tem uma seção schemas de nível superior, que contém um par de nome/valor de ID do esquema para o objeto. Os IDs de esquema são exclusivos por API e usados para identificar o esquema na seção methods do documento de descoberta:

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

O serviço Discovery de APIs usa o esquema JSON rascunho-03 para suas representações de esquema. Veja um snippet do esquema JSON para o recurso de URL com um recurso de resposta 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
    }
  }
}

Os campos em negrito mostram o mapeamento entre o esquema JSON e a resposta real.

Os esquemas também podem conter referências a outros esquemas. Se você estiver criando uma biblioteca de cliente, ela poderá ajudar a modelar de forma eficaz os objetos de uma API nas classes de modelo de dados. No exemplo do Rollout acima, a propriedade trafficPercentStrategy é na referência um esquema com ID TrafficPercentStrategy. Ao analisar a seção schemas, você encontrará o esquema TrafficPercentStrategy. O valor desse esquema pode ser substituído pela propriedade trafficPercentStrategy no recurso Rollout. A sintaxe $ref vem da especificação do esquema JSON.

Os métodos também podem fazer referência a esquemas ao indicar o corpo da solicitação e da resposta. Consulte a seção Métodos para mais detalhes.

Métodos

A base do documento Discovery é baseada em métodos. Os métodos são as operações que podem ser realizadas em uma API. Você encontrará a seção methods em várias áreas do documento Discovery, incluindo no nível superior (que chamamos de métodos no nível da API) ou resources.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

Embora uma API possa ter métodos no nível da API, um recurso precisa ter uma seção methods.

Cada seção methods é um mapa de chave-valor do nome do método para outros detalhes sobre esse método. O exemplo abaixo documenta três métodos, get, list e create:

"methods": {
  "get": { //details about the "get" method },
  "list": { //details about the "list" method },
  "create": { //details about the "create" method }
}

Por fim, a seção de cada método detalha várias propriedades sobre o método. Veja um exemplo do 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 },
},

Esta seção contém detalhes gerais do método, como uma ID exclusiva para identificar o método, o httpMethod a ser usado e o path do método. Para ver detalhes sobre como usar a propriedade path para calcular o URL completo do método, consulte a seção Escrever uma solicitação. Além dessas propriedades gerais do método, existem outras que conectam o método a outras seções no documento Discovery:

Escopos

A seção auth definida anteriormente nesta documentação contém informações sobre todos os escopos compatíveis com uma API específica. Se um método for compatível com um desses escopos, ele terá uma matriz de escopos. Há uma entrada nessa matriz para cada escopo compatível com o método. Por exemplo, a seção scopes do método get da API Google Cloud Service Management tem esta aparência:

"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"
]

Observe que a escolha de um escopo de autenticação para usar no aplicativo depende de vários fatores, como quais métodos estão sendo chamados e quais parâmetros são enviados com o método. Portanto, a decisão de qual escopo usar será deixada para o desenvolvedor. O Discovery documenta apenas quais escopos são válidos para um método.

Solicitação e resposta

Se o método tiver um corpo de solicitação ou resposta, eles serão documentados nas seções request ou response, respectivamente. No exemplo do get acima, o método tem um corpo response:

"response": {
  "$ref": "Rollout"
}

A sintaxe acima indica que o corpo da resposta é definido por um esquema JSON com um ID de Rollout. Esse esquema pode ser encontrado na seção de esquemas de nível superior. Os corpos de solicitação e resposta usam a sintaxe $ref para se referir a esquemas.

Parâmetros

Se um método tiver parâmetros que precisam ser especificados pelo usuário, eles serão documentados na seção parameters no nível do método. Esta seção contém um mapeamento de chave-valor do nome do parâmetro para mais detalhes sobre esse parâmetro:

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

No exemplo acima, há dois parâmetros para o método get:serviceName e rolloutId. Os parâmetros podem ser inseridos em path ou no URL query. A propriedade location indica onde a biblioteca de cliente precisa colocar o parâmetro.

Há muitas outras propriedades que descrevem o parâmetro, incluindo os dados do parâmetro type (útil para idiomas tipados) se o parâmetro é required e se o parâmetro é uma enumeração. Consulte o Guia de referência para mais detalhes sobre as propriedades.

Ordem dos parâmetros

As bibliotecas de cliente podem estruturar as interfaces de muitas maneiras. Uma delas é ter um método com cada parâmetro de API na assinatura do método. No entanto, como o JSON é um formato não ordenado, é difícil saber programaticamente como ordenar os parâmetros na assinatura do método. A matriz parameterOrder fornece uma ordem de parâmetro fixa para fazer solicitações. A matriz lista o nome de cada parâmetro em ordem de importância; pode conter parâmetros de caminho ou de consulta, mas todos os parâmetros da matriz são obrigatórios. No exemplo acima, uma assinatura de método Java pode ser parecida com esta:

public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);

O primeiro valor na matriz parameterOrder, serviceName, também é o primeiro elemento na assinatura do método. Se houver outros parâmetros na matriz parameterOrder, eles vão depois do parâmetro serviceName. Como a matriz parameterOrder contém apenas os parâmetros obrigatórios, é recomendável incluir também uma maneira de os usuários especificarem parâmetros opcionais. O exemplo acima faz isso com o mapa optionalParameters.

Upload de mídia

Se um método for compatível com o upload de mídia, como imagens, áudio ou vídeo, o local e os protocolos compatíveis para o upload dessa mídia serão documentados na seção mediaUpload. Esta seção contém detalhes sobre quais protocolos de upload são compatíveis e informações sobre quais tipos de mídia podem ser enviados:

"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"
    }
  }
}

No exemplo acima, a propriedade supportsMediaUpload é um valor booleano que determina se o método oferece suporte ao upload de mídia. Se o valor for verdadeiro, a seção mediaUpload documentará os tipos de mídia que podem ser enviados.

A propriedade accept é uma lista de intervalos de mídia que determinam quais tipos MIME são aceitáveis para upload. O endpoint mostrado no exemplo acima aceitará qualquer formato de imagem.

A propriedade maxSize tem o tamanho máximo de um upload. O valor é uma string em unidades de MB, GB ou TB. No exemplo acima, os uploads são limitados a um tamanho máximo de 10 MB. Esse valor não reflete a cota de armazenamento restante de um usuário individual para essa API. Por isso, mesmo que o upload seja inferior a maxSize, a biblioteca de cliente ainda deve estar preparada para lidar com um upload que falha devido à falta de espaço.

A seção protocols lista os protocolos de upload compatíveis com um método. O protocolo simple está simplesmente POSTANDO a mídia para o endpoint especificado em uma única solicitação HTTP. O protocolo resumable implica que o endpoint fornecido no URI path é compatível com o protocolo de upload recuperável. Se a propriedade multipart for true, o endpoint aceitará uploads de várias partes. Isso significa que a solicitação JSON e a mídia podem ser unidas em um corpo mutuamente/relacionado e enviadas juntas. Os protocolos simple e resumable podem oferecer suporte a uploads de várias partes.

A propriedade path é um modelo de URI e precisa ser expandida da mesma forma que a propriedade path para o método, conforme descrito na seção Escrever uma solicitação.

Download de mídia

Se um método for compatível com o download de mídia, como imagens, áudio ou vídeo, isso será indicado pelo parâmetro supportsMediaDownload:

"supportsMediaDownload": true,

Ao fazer o download da mídia, é necessário definir o parâmetro de consulta alt como media no URL da solicitação.

Se a propriedade useMediaDownloadService do método da API for true, insira /download antes de servicePath para evitar o redirecionamento. Por exemplo, o caminho de download será /download/youtube/v3/captions/{id} se a concatenação de servicePath e path for /youtube/v3/captions/{id}. É recomendável criar um URL de download de mídia com /download, mesmo quando useMediaDownloadService for falso.

Parâmetros comuns

O documento Discovery de nível superior contém uma propriedade parameters. Essa seção é semelhante à seção de parâmetros de cada método, mas pode ser aplicada a qualquer método na API.

Por exemplo, os métodos get, insert ou list da API Google Cloud Service Management podem ter um parâmetro prettyPrint nos parâmetros de solicitação, o que formatará a resposta de todos esses métodos em um formato legível. Veja uma lista de parâmetros comuns:

Recursos

Em alguns casos, as APIs são compatíveis com recursos personalizados fora do escopo do restante do documento Discovery. Elas são coletadas na matriz features. A matriz de atributos contém um rótulo de string para cada recurso especial compatível com a API. Atualmente, dataWrapper é o único recurso compatível, mas outros recursos podem ser compatíveis no futuro.

"features": dataWrapper

O recurso dataWrapper indica que todas as solicitações e respostas da API estão encapsuladas em um objeto JSON data. Esse é um recurso das APIs mais antigas do Google, mas será descontinuado no futuro. As APIs a seguir são compatíveis com o recurso dataWrapper: Moderator v1 e Tradutor v2.

Como desenvolvedor de uma biblioteca de cliente, se uma API for compatível com o recurso "dataWrapper", faça o seguinte:

1. Em solicitações: envolva o recurso da solicitação em um objeto JSON data.
2. Nas respostas: encontre o recurso dentro de um objeto JSON data.

Os esquemas no documento do Discovery não contêm o wrapper de dados. Por isso, é necessário adicioná-los e removê-los explicitamente. Por exemplo, suponha que haja uma API com um recurso chamado "Foo" semelhante a esta:

{
  "id": 1,
  "foo": "bar"
}

Antes de inserir esse recurso usando a API, é necessário envolvê-lo em um elemento de dados:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

Por outro lado, quando você recebe uma resposta da API, ela também contém o wrapper de dados:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

Para ter o recurso definido pelo esquema, você precisa remover o wrapper de dados:

{
  "id": 1,
  "foo": "bar"
}

Documentação in-line

Cada documento do Discovery é anotado com vários campos description, que fornecem documentação in-line para a API. Os campos description podem ser encontrados para os seguintes elementos da API:

• API em si
• Escopos do OAuth
• Esquemas de recursos
• Métodos de API
• Parâmetros do método
• Valores aceitáveis para determinados parâmetros

Esses campos são especialmente úteis se você quer usar o Serviço de descoberta de APIs do Google para gerar documentação legível para uma biblioteca de cliente, por exemplo, JavaDoc.

Próximas etapas

• Como criar uma biblioteca de cliente