Requisitos de integração de API

Este documento descreve os requisitos gerais de uma API que você quer adicionar como provedor de tipos do Deployment Manager. Use essas diretrizes para entender as características necessárias para uma API funcionar com o Deployment Manager. Se a API não corresponder exatamente às especificações descritas aqui, tente resolver as inconsistências por meio das Opções avançadas de API.

O documento descritor da API deve ser válido

O documento descritor descreve a API e os recursos dela. Apenas APIs com suporte de uma especificação OpenAPI ou um Descoberta do Google o documento descritor do cliente pode ser integrado ao Deployment Manager. Para informações detalhadas sobre como criar uma especificação OpenAPI, consulte o repositório da OpenAPI no GitHub.

O ponto de extremidade do documento descritor da API deve ser acessível

O Deployment Manager faz uma solicitação HTTP para receber o documento descritor da API. Portanto, o documento descritor precisa estar hospedado em um local que o Deployment Manager pode acessar. Esse local pode ser um URL disponível publicamente ou um ponto de extremidade protegido por autenticação básica.

A API deverá aceitar autenticação básica ou OAuth2 se estiver hospedada em determinados serviços do Google

Atualmente, o Deployment Manager oferece suporte para autenticação básica (nome de usuário e senha) e autenticação OAuth 2.0 para determinadas APIs hospedadas no Google Kubernetes Engine ou no Google Endpoints. Você pode configurar a autenticação para usar a conta do serviço do projeto.

Para mais informações, leia sobre como criar um provedor de tipos.

A API deve oferecer suporte para as operações de criação, leitura, atualização e exclusão (CRUD, na sigla em inglês)

A API em questão precisa ser uma API RESTful compatível com as operações CRUD. Ou seja, deve ter métodos que executam os seguintes tipos de operação:

  • Criação: cria recursos. Precisa ser uma solicitação HTTP POST.
  • Leitura: extrai informações sobre os recursos da API. Precisa ser uma solicitação HTTP GET.
  • Atualização: atualiza recursos. Precisa ser uma solicitação HTTP PUT
  • Exclusão: exclui recursos. Precisa ser uma solicitação HTTP DELETE.

APIs que oferecem suporte parcial às operações CRUD também funcionam. No entanto, o comportamento será diferente, dependendo das operações disponíveis.

Aceita solicitações GET Aceita solicitações CREATE Aceita solicitações UPDATE Aceita solicitações DELETE API com comportamento especial?
Sim Sim Sim Sim Nenhum.
Sim Sim Sim Não Os usuários podem abandonar um recurso, mas não o excluir.
Sim Sim Não Sim Qualquer alteração em um recurso existente resulta em falha. Os usuários precisam excluir e recriar o recurso para atualizá-lo.
Sim Sim Não Não Ambos os comportamentos descritos acima.
Sim Não Sim Sim Se a API não oferece suporte à criação de solicitações, os usuários podem adicionar os recursos existentes à implantação por meio da atualização dessa implantação com a política ACQUIRE.
Sim Não Sim Não Os usuários podem adquirir um recurso ou atualizá-lo após a aquisição, mas não o excluir.
Sim Não Não Sim Os usuários podem excluir e conseguir recursos ou podem adicionar um recurso existente a uma implantação.
Sim Não Não Não Os usuários podem adquirir um recurso existente ou removê-lo com a política ABANDON.

Todos os parâmetros de caminho e consulta devem ser resolvidos com êxito

É necessário que todos os parâmetros de caminho e consulta da API existam como parte do corpo do recurso ou em todos os métodos da API, para que o Deployment Manager faça a correspondência correta com o parâmetro quando o usuário o fornece. As condições a seguir se aplicam aos parâmetros de caminho e consulta.

Todos os parâmetros de caminho/consulta de POST precisam ser parâmetros de PUT

O seguinte é inválido porque há um myParameter para POST, mas não para PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Todos os parâmetros do método de não POST precisam estar presentes em todas as interfaces do método ou fazer parte do recurso, com considerações especiais se o parâmetro for gerado pelo servidor.

Na melhor das hipóteses, a API pode ter essa forma, em que o parâmetro name é exibido para todos os métodos.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

Outra hipótese é que um campo pode ser exibido como parâmetro de caminho para um dos métodos, mas não para outros métodos. Nesse caso, o campo deve ser parte do recurso da API. Por exemplo:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

Neste exemplo, a suposição é de que id é um valor gerado pelo servidor e que está presente no recurso, mas não está presente quando é feita uma solicitação POST. Se a propriedade id fosse necessária para fazer uma solicitação a um recurso existente, mas não estivesse no recurso e nem disponível no caminho, isso impediria a portabilidade da API para o Deployment Manager.

O comportamento sutil da API requer outra configuração

Determinados comportamentos da API requerem configuração adicional para integrá-la ao Deployment Manager. Isso inclui os comportamentos a seguir:

  • Valores gerados pelo servidor: alguns recursos da API têm propriedades geradas pelo servidor que mudam após cada solicitação ou quando um determinado evento acontece na API. É possível usar as opções avançadas da API para instruir o Deployment Manager a pegar o valor novo sempre que uma solicitação é realizada.

    Por exemplo, uma API pode exigir a propriedade de impressão digital mais recente de um recurso antes de permitir uma solicitação de atualização. Use as Opções avançadas da API para instruir o Deployment Manager a pegar esse valor sempre que o usuário fizer uma solicitação para atualizar uma implantação com ele.

  • Manipulação de entradas do usuário: por exemplo, se a API exige que o valor de um campo sempre tenha como prefixo o ID do projeto, use mapeamentos de entrada para adicionar essa informação automaticamente, em vez de obrigar os usuários a adicioná-la manualmente.

  • Valores de campo que mudam a cada método: no caso dos métodos que reutilizam o mesmo campo, mas com valores diferentes, é possível usar as opções de API para instruir o Deployment Manager sobre quando usar cada valor.

Para mais informações, leia Como configurar as opções avançadas de API.

Próximas etapas