Métodos personalizados

Neste capítulo, você aprenderá como usar métodos personalizados para projetos de API.

Os métodos personalizados referem-se a métodos de API além dos cinco métodos padrão. Eles só devem ser usados para funcionalidades que não podem ser expressas facilmente por meio de métodos padrão. Em geral, os designers da API precisam escolher os métodos padrão em vez dos métodos personalizados, sempre que possível. Os métodos padrão têm uma semântica mais simples, bem definida e que a maioria dos desenvolvedores conhece, por isso são mais fáceis de usar e menos propensos a erros. Outra vantagem dos métodos padrão é que a plataforma da API tem melhor compreensão e compatibilidade para métodos padrão, como faturamento, gerenciamento de erros, registro e monitoramento.

Um método personalizado pode ser associado a um recurso, um conjunto ou um serviço. Isso pode levar a uma solicitação arbitrária e retornar uma resposta arbitrária, além de também ser compatível com solicitação e resposta de transmissão.

Os nomes dos métodos personalizados precisam seguir as convenções de nomenclatura de métodos.

Mapeamento de HTTP

Para os métodos personalizados, eles usarão o seguinte mapeamento de HTTP genérico:

https://service.name/v1/some/resource/name:customVerb

A razão para usar : em vez de / para separar o verbo personalizado do nome do recurso é ser compatível com caminhos arbitrários. Por exemplo, desfazer a exclusão de um arquivo pode mapear para POST /files/a/long/file/name:undelete

As seguintes diretrizes deverão ser aplicadas ao escolher o mapeamento de HTTP:

Nos métodos personalizados, é necessário usar o verbo POST do HTTP, já que ele tem a semântica mais flexível. A exceção são os métodos que servem como um "list" ou "get" alternativo, em que GET pode ser usado. (para detalhes, consulte o terceiro item).
Nos métodos personalizados, o PATCH do HTTP pode ser usado, mas outros verbos HTTP não. Nesses casos, é preciso seguir a semântica HTTP padrão do verbo nos métodos.
Os métodos personalizados em que o GET do HTTP é usado precisam ser idempotentes e não ter efeitos colaterais. Por exemplo, em métodos personalizados para implementação de visualizações especiais no recurso, é necessário usar o GET do HTTP.
Os campos da mensagem de solicitação que recebem o nome do recurso ou o conjunto ao qual o método personalizado está associado devem ser mapeados para o caminho do URL.
O caminho do URL precisa terminar com um sufixo composto de dois pontos seguido do verbo personalizado.
Se o verbo HTTP usado para o método personalizado permitir um corpo de solicitação HTTP (isso se aplica a POST, PUT, PATCH ou um verbo HTTP personalizado), a configuração HTTP desse método personalizado deve usar a cláusula body: "*" e todos os campos restantes da mensagem de solicitação deverão ser mapeados para o corpo da solicitação HTTP.
Se o verbo HTTP usado para o método personalizado não aceitar um corpo de solicitação HTTP (GET, DELETE), a configuração HTTP desse método não poderá usar a cláusula body e todos os campos restantes da mensagem de solicitação precisam ser mapeados para os parâmetros de consulta do URL.

AVISO: se um serviço implementa várias APIs, o produtor da API precisa criar cuidadosamente a configuração do serviço para evitar conflitos verbais personalizados entre as APIs.

// This is a service level custom method.
rpc Watch(WatchRequest) returns (WatchResponse) {
  // Custom method maps to HTTP POST. All request parameters go into body.
  option (google.api.http) = {
    post: "/v1:watch"
    body: "*"
  };
}

// This is a collection level custom method.
rpc ClearEvents(ClearEventsRequest) returns (ClearEventsResponse) {
  option (google.api.http) = {
    post: "/v3/events:clear"
    body: "*"
  };
}

// This is a resource level custom method.
rpc CancelEvent(CancelEventRequest) returns (CancelEventResponse) {
  option (google.api.http) = {
    post: "/v3/{name=events/*}:cancel"
    body: "*"
  };
}

// This is a batch get custom method.
rpc BatchGetEvents(BatchGetEventsRequest) returns (BatchGetEventsResponse) {
  // The batch get method maps to HTTP GET verb.
  option (google.api.http) = {
    get: "/v3/events:batchGet"
  };
}

Casos de uso

Alguns cenários adicionais em que métodos personalizados podem ser a escolha certa:

Reiniciar uma máquina virtual. As alternativas do projeto poderiam ser "criar um recurso de reinicialização no conjunto de reinicializações", o que parece complexo de maneira desproporcional, ou "a máquina virtual tem um estado mutável que o cliente pode atualizar de EXECUTANDO para REINICIANDO", o que abriria perguntas sobre quais outras transições de estado são possíveis. Além disso, a reinicialização é um conceito bem conhecido que pode ser traduzido bem para um método personalizado que atende intuitivamente às expectativas dos desenvolvedores.
Enviar e-mail. Criar uma mensagem de e-mail não necessariamente a enviará (rascunho). Comparado com a alternativa de projeto (mover uma mensagem para um conjunto de "Caixa de saída"), o método personalizado tem a vantagem de ser mais visível pelo usuário da API e modelar o conceito de maneira mais direta.
Promover um funcionário. Se implementado como um update padrão, o cliente teria que replicar as políticas corporativas que regem o processo de promoção para garantir que a promoção aconteça no nível correto, dentro da mesma carreira etc.
Métodos de lote. Para os métodos críticos de desempenho, pode ser útil fornecer métodos de lote personalizados para reduzir a sobrecarga por solicitação. Por exemplo, accounts.locations.batchGet.

Alguns exemplos em que um método padrão é uma escolha melhor que um método personalizado:

Recursos de consulta com diferentes parâmetros de consulta (use list com a filtragem de lista padrão).
Alteração simples de propriedade de recurso (use o método update padrão com máscara de campo).
Dispensar uma notificação (use o método delete padrão).

Métodos personalizados comuns

Veja abaixo uma lista selecionada de nomes de métodos personalizados usados normalmente ou úteis. Os designers da API devem considerar esses nomes antes de introduzir os seus próprios para facilitar a consistência em todas as APIs.

Nome do método	Verbo personalizado	Verbo HTTP	Observação
`Cancel`	`:cancel`	`POST`	Cancele uma operação pendente, como `operations.cancel`.
`BatchGet`	`:batchGet`	`GET`	Batch get de múltiplos recursos Consulte detalhes na descrição da lista.
`Move`	`:move`	`POST`	Mova um recurso de um pai para outro, como `folders.move`.
`Search`	`:search`	`GET`	Alternativa à lista para buscar dados que não aderem à semântica de lista, como `services.search`.
`Undelete`	`:undelete`	`POST`	Restaure um recurso que foi excluído anteriormente, como `services.undelete`. O período de armazenamento recomendado é de 30 dias.

Métodos padrão

Campos padrão