Práticas recomendadas para adicionar um provedor de tipos

Nesta página, você verá as práticas recomendadas para criar e adicionar uma API ou adicionar uma API atual ao Deployment Manager como um provedor de tipos.

O Deployment Manager permite adicionar APIs como provedores de tipos para expor os recursos da API como tipos que podem ser chamados na configuração. Para facilitar o processo, adote as práticas recomendadas descritas aqui ao configurar ou criar uma API.

Como criar uma API nova

Se você estiver criando uma API nova a ser integrada ao Deployment Manager, adote as práticas recomendadas abaixo.

Use os métodos padrão criar, ler, atualizar e excluir (CRUD, na sigla em inglês) e evite métodos personalizados

Se possível, evite criar métodos personalizados. Atenha-se aos métodos REST padrão, como GET, POST, PUT e DELETE. Esses métodos são reconhecidos pelo Deployment Manager e podem ser mapeados automaticamente.

No caso das APIs do Discovery, é necessário nomear os métodos de API de acordo com o mapeamento a seguir:

Método REST Nome recomendado para a API
POST create ou insert
GET get
PUT update
DELETE delete

No caso das especificações da OpenAPI, não é possível dar aos métodos de API nomes diferentes daqueles dos métodos REST padrão.

Use caminhos de recurso previsíveis

No caso das especificações da OpenAPI, o Deployment Manager oferece suporte para dois comportamentos para identificar uma interface RESTful. O primeiro é aplicado quando todos os métodos REST de um recurso pertencem ao mesmo caminho de recurso:

/foo/{name}
  post:
  get:
  delete:
  put:

Se for necessário separar os métodos, use o mesmo caminho de recurso. Por exemplo, o método a seguir é válido porque se refere ao mesmo recurso /foo:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

No entanto, o próximo exemplo é inválido porque se refere a dois recursos diferentes, do ponto de vista do Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

Em casos raros, você pode querer nomear os caminhos de recurso como no exemplo abaixo:

foo/create
  post:

foo/delete
  delete:

Como o Deployment Manager não consegue identificar a interface RESTful, eles serão inválidos.

Use nomes consistentes em toda a interface

Mantenha os mesmos nomes de entradas e caminhos nos métodos POST e PUT. Isso também se aplica aos valores dos parâmetros. Ou seja, mantenha a mesma sintaxe nos valores dos parâmetros de todos os métodos.

Por exemplo, se você tiver um parâmetro denominado email para o corpo de uma solicitação POST, não denomine o mesmo parâmetro emailAddress para a solicitação PUT.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

Se for necessário adicionar esse tipo de comportamento, configure as opções avançadas de API para instruir o Deployment Manager a lidar com a situação.

Além disso, mantenha o mesmo corpo da solicitação para os métodos POST e PUT. Para os métodos GET e DELETE, somente o caminho é aplicável, porque não há um corpo de solicitação para esses métodos.

Como integrar uma API atual

Integrar uma API existente pode ser um processo com várias facetas, dependendo da API. Portanto, não há um conjunto concreto de práticas recomendadas que podem ser aplicadas genericamente em todas as APIs. A lista a seguir reúne recomendações gerais que podem ajudar a encontrar uma maneira de integrar uma API existente.

  • Use um wrapper para APIs não RESTful.

    Se a API existente não for uma RESTful API, você poderá criar um wrapper para expor apenas os métodos REST.

  • Se a API for quase RESTful, identifique e atualize a API.

    Se a API for quase RESTful e tiver apenas alguns comportamentos não REST, você poderá atualizá-la para resolver esses comportamentos.

  • Valores gerados pelo servidor sempre requerem um mapeamento de entrada.

    Se a API tiver valores gerados pelo servidor que são exigidos pelos métodos, você precisará configurar os mapeamentos de entrada para conseguir o valor gerado pelo servidor e mapeá-lo para cada solicitação.

A seguir