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 devem 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 do método.

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, cancelar 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 no método personalizado for compatível com um corpo de solicitação HTTP (POST, PUT, PATCH ou um verbo personalizado), será necessário usar a cláusula body: "*" na configuração desse método. Além disso, todos os campos restantes da mensagem de solicitação precisarã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 de tal método não poderá usar a cláusula body, e todos os campos restantes da mensagem de solicitação deverão mapear os parâmetros da 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, na 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 parâmetros diferentes (use o método list padrão com filtragem de lista padrão).
  • Alteração simples de propriedade de recursos (use o método update padrão com máscara de campo).
  • Descartar 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
Cancelar :cancel POST Cancelar uma operação pendente (criação, cálculo etc.)
BatchGet <substantivo plural> :batchGet GET Batch get de múltiplos recursos (consulte detalhes na descrição da lista).
Mover :move POST Mover um recurso de um dos pais para outro.
Pesquisar :search GET Opção alternativa à lista para conseguir dados que não aderem à semântica da lista.
Cancelar exclusão :undelete POST Restaurar um recurso que foi excluído anteriormente. O período de armazenamento recomendado é de 30 dias.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…