Requisitos da API para integrar uma API

Este documento descreve os requisitos gerais de uma API que quer adicionar como fornecedor de tipos ao Deployment Manager. Use estas diretrizes para compreender as caraterísticas de uma API que o Deployment Manager espera. Se a sua API não corresponder exatamente às especificações descritas aqui, pode resolver estas inconsistências através das opções avançadas da API.

A API tem um documento descritor válido

Um documento descritor descreve uma API e os respetivos recursos. Apenas as APIs suportadas por uma especificação OpenAPI ou um documento descritor Google Discovery podem ser integradas com o Deployment Manager. Para obter informações abrangentes sobre como criar uma especificação OpenAPI, consulte o repositório do GitHub da OpenAPI.

O ponto final do documento descritor da API está acessível

O Deployment Manager faz um pedido HTTP para obter o documento descritor da API, pelo que deve certificar-se de que aloja o documento descritor num local acessível ao Deployment Manager. Pode ser um URL disponível publicamente ou um ponto final protegido por autenticação básica.

A API aceita a autenticação básica ou o OAuth2 se estiver alojada em determinados serviços Google

Atualmente, o Deployment Manager suporta a autenticação básica (nome de utilizador e palavra-passe) e a autenticação OAuth 2.0 para determinadas APIs alojadas no Google Kubernetes Engine ou nos Google Endpoints. Pode configurar a autenticação para usar a conta de serviço do projeto.

Para mais informações, leia o artigo Criar um fornecedor de tipos.

Suporta operações de criação, leitura, atualização e eliminação (CRUD)

A API em questão tem de ser uma API RESTful que suporte operações CRUD. Ou seja, existem métodos que realizam as seguintes ações:

  • Operações de criação: cria recursos. Tem de ser um pedido HTTP POST.
  • Operações de leitura: obtém informações sobre os recursos da API. Tem de ser um pedido HTTP GET.
  • Operações de atualização: atualiza um recurso. Tem de ser um pedido HTTP PUT
  • Eliminar operações: elimina recursos. Tem de ser um pedido HTTP DELETE.

Uma API que apenas suporta operações CRUD parciais continua a funcionar, mas o comportamento é diferente consoante as operações disponíveis.

Suporta pedidos GET Suporta pedidos CREATE Suporta pedidos UPDATE Suporta pedidos DELETE Comportamento especial da API?
Sim Sim Sim Sim Nenhum.
Sim Sim Sim Não Os utilizadores podem abandonar um recurso, mas não o podem eliminar.
Sim Sim Não Sim Qualquer alteração a um recurso existente falharia. Os utilizadores têm de eliminar e recriar um recurso para o atualizar.
Sim Sim Não Não Ambos os comportamentos descritos acima.
Sim Não Sim Sim Se uma API não suportar pedidos de criação, os utilizadores podem adicionar recursos existentes à implementação atualizando a implementação com a política ACQUIRE.
Sim Não Sim Não Os utilizadores podem adquirir um recurso ou atualizá-lo depois de o terem adquirido, mas não podem eliminá-lo.
Sim Não Não Sim Os utilizadores podem eliminar um recurso e obter um recurso, ou podem adicionar um recurso existente a uma implementação.
Sim Não Não Não Os utilizadores podem adquirir um recurso existente ou removê-lo com a política ABANDON.

Todos os parâmetros de caminho e de consulta são resolvidos com êxito

Todos os parâmetros de caminho e de consulta da API têm de existir como parte do corpo do recurso ou existir em todos os métodos da API, para que o Deployment Manager possa fazer corresponder o parâmetro quando um utilizador o fornece. As seguintes condições aplicam-se aos parâmetros de caminho e de consulta.

Cada parâmetro de caminho/consulta para um POST tem de ser um parâmetro para PUT

O seguinte é inválido porque myParameter existe 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 para o método não POST têm de estar presentes em todas as interfaces de métodos ou como parte do recurso, com considerações especiais se este parâmetro for gerado pelo servidor.

No melhor cenário, a API pode ter o seguinte aspeto, em que o parâmetro name aparece 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}

Noutro cenário, um campo pode aparecer como um parâmetro de caminho para um método, mas não como um parâmetro de caminho para outros métodos. Neste caso, o campo deve fazer 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 é que id é um valor gerado pelo servidor que está presente no recurso, mas não está presente quando faz um pedido POST. Se a propriedade id fosse necessária para fazer um pedido a um recurso existente, mas a propriedade não estivesse no recurso ou disponível no caminho, isto causaria problemas na portabilidade da API para o Deployment Manager.

O comportamento subtil da API requer configuração adicional

Existem determinados comportamentos da API que requerem uma configuração adicional da API para integrar a API com o Deployment Manager. Estes comportamentos incluem:

  • Valores gerados pelo servidor: alguns recursos da API têm propriedades geradas pelo servidor que mudam após cada pedido ou quando ocorre um determinado evento na API. Pode usar opções avançadas da API para indicar ao Deployment Manager que obtenha este novo valor sempre que é feito um pedido.

    Por exemplo, uma API pode exigir a propriedade de impressão digital mais recente de um recurso antes de permitir um pedido de atualização. Use as Opções avançadas da API para indicar ao Deployment Manager que obtenha este valor sempre que o utilizador fizer um pedido para atualizar uma implementação com este.

  • Manipular a entrada do utilizador: por exemplo, se a sua API exigir que o valor de um campo seja sempre precedido de um ID do projeto, pode usar mapeamentos de entrada para adicionar automaticamente essas informações, em vez de forçar os utilizadores a adicioná-las manualmente.

  • Valores de campos que mudam com cada método: para métodos que reutilizam o mesmo campo, mas com valores diferentes, pode usar as opções da API para expressar ao Deployment Manager quando usar que valor.

Para mais informações, leia o artigo Definir opções avançadas da API.

O que se segue?