Práticas recomendadas para adicionar um fornecedor de tipos

Esta página descreve as práticas recomendadas para criar uma nova API a adicionar ao Deployment Manager como um fornecedor de tipos ou adicionar uma API existente como um fornecedor de tipos.

O Deployment Manager permite-lhe adicionar APIs como fornecedores de tipos para expor os recursos da API como tipos que pode chamar na respetiva configuração. Para facilitar o processo, use estas práticas recomendadas quando configurar ou criar uma API.

Criar uma nova API

Se estiver a criar uma nova API que pretende integrar com o Deployment Manager, use estas práticas recomendadas.

Use métodos padrão de criação, leitura, atualização e eliminação (CRUD) e evite métodos personalizados

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

Para as APIs Discovery, deve dar nomes aos métodos de API de acordo com o seguinte mapeamento:

Método REST Nomenclatura de APIs recomendada
POST create ou insert
GET get
PUT update
DELETE delete

Para especificações da OpenAPI, não pode atribuir aos métodos da API nomes diferentes dos métodos REST padrão.

Use caminhos de recursos previsíveis

Para as especificações da OpenAPI, o Deployment Manager suporta dois comportamentos para identificar uma interface RESTful. A primeira é se todos os métodos REST para um recurso pertencerem ao mesmo caminho do recurso:

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

Se tiver de separar os métodos, use o mesmo caminho do recurso. Por exemplo, o seguinte é válido porque se refere ao mesmo recurso /foo:

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

No entanto, o seguinte é 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, pode ser tentador dar nomes aos seus caminhos de recursos da seguinte forma:

foo/create
  post:

foo/delete
  delete:

Isto é inválido do ponto de vista do Deployment Manager porque não consegue identificar a interface RESTful.

Use uma nomenclatura consistente na interface

Mantenha os nomes de entrada e de caminho iguais entre os métodos POST e PUT. Isto também se aplica aos valores dos parâmetros. Ou seja, mantenha a sintaxe dos valores dos parâmetros igual em todos os métodos.

Por exemplo, se tiver um parâmetro denominado email para o corpo do pedido de um pedido POST, não atribua o nome emailAddress ao mesmo parâmetro para o pedido PUT.

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

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

Se tiver de adicionar este tipo de comportamento, indique ao Deployment Manager como processá-lo definindo as opções avançadas da API.

Além disso, mantenha o corpo do pedido para os métodos POST e PUT igual. Para os métodos GET e DELETE, apenas o caminho é aplicável, uma vez que não existe um corpo do pedido para estes métodos.

Integrar uma API existente

A integração de uma API existente pode ser um processo muito variado, consoante a API. Como tal, não existe um conjunto concreto de práticas recomendadas que possa ser aplicado de forma genérica a todas as APIs. Segue-se uma lista de conselhos gerais que podem ajudar quando considerar formas de integrar uma API existente.

  • Use um wrapper de API para APIs não RESTful.

    Se uma API existente não for uma API RESTful, pode criar um wrapper de API para expôr apenas os métodos REST.

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

    Se a sua API for quase RESTful e tiver apenas alguns comportamentos não REST, pode atualizar a API para resolver estes comportamentos.

  • Os valores gerados pelo servidor requerem sempre um mapeamento de entrada.

    Se a sua API tiver valores gerados pelo servidor que são necessários para os métodos da API, tem de configurar mapeamentos de entrada para obter o valor gerado pelo servidor e mapeá-lo para cada pedido.

O que se segue?