O método HTTP informa a intenção geral da chamada: consultar, criar, substituir, alterar ou remover. Conhecer cada método ajuda a ler o log, mas o contrato de cada operação continua definindo os campos e o comportamento.
GET, a consulta
O GET pede a representação de um recurso ou de uma lista. No gateway de pagamento, GET /v1/pagamentos/PAG-0001 consulta uma cobrança, e GET /v1/pagamentos?pedido_id=PED-0001 lista as cobranças de um pedido. Os filtros vão na URL, porque um corpo enviado em um GET não tem significado definido pelo HTTP e pode ser recusado.
A resposta comum com dados tem o código 200, de sucesso. O código 404 informa que o recurso pedido não foi encontrado. Uma lista sem nenhum item também pode vir com o código 200, conforme o contrato.
POST, a criação ou a execução
O POST envia dados para processamento. Ele pode criar um recurso, executar uma ação ou até fazer uma consulta que precisa de um corpo. As respostas comuns são o código 201, de criação, o 200, de operação atendida, e o 202, de aceite sem conclusão confirmada.
Na criação de uma cobrança, o serviço gera o número da cobrança e o devolve na resposta. Algumas APIs impedem a duplicidade com um número de pedido único ou com uma chave de idempotência, e o código 409, de conflito, pode indicar uma repetição recusada. Essas proteções e o significado do 409 dependem do contrato e não surgem automaticamente pelo uso do POST.
PUT e PATCH, a substituição e a alteração
O PUT pede a criação ou a substituição do recurso no endereço indicado. As respostas comuns são o código 200 ou o 204, na substituição, e o 201, na criação. A representação exigida e o tratamento dos campos omitidos dependem da operação. Em uma substituição completa, enviar só o e-mail de um cadastro pode apagar os outros campos ou devolvê-los ao valor padrão.
O PATCH descreve uma alteração parcial, só dos campos informados, em um formato definido pelo fornecedor. Definir o e-mail com um valor pode ser idempotente, enquanto somar uma quantidade ao estoque a cada chamada não é.
DELETE, HEAD e OPTIONS
O DELETE pede a remoção do recurso, e a aplicação pode implementar essa remoção como uma exclusão lógica, uma marca que esconde o registro sem apagá-lo. As respostas comuns são o código 204, o 200 e o 202, e uma repetição pode receber o 404.
O cancelamento e o estorno de um pagamento costumam ser operações próprias, muitas vezes feitas por POST, com histórico e regras específicas. O DELETE não substitui esses procedimentos.
O HEAD pede só os cabeçalhos que um GET devolveria, sem o corpo. O OPTIONS consulta as opções de comunicação de um recurso, e os navegadores o usam em algumas verificações de segurança antes de uma chamada a outro site.
Um endereço, várias intenções
Em uma API de cadastro de clientes, o mesmo endereço atende operações diferentes, conforme o método:
GET /clientes: lista os clientes;POST /clientes: cadastra um cliente;GET /clientes/0001: consulta o cliente 0001;PUT /clientes/0001: substitui o cadastro inteiro do cliente 0001;PATCH /clientes/0001: altera parte do cadastro do cliente 0001;DELETE /clientes/0001: remove ou inativa o cliente 0001.
A operação é a combinação do método com o endereço. O caminho, sozinho, não indica a intenção da chamada.
A alteração sobre dados antigos
Dois programas podem ler o mesmo cadastro e enviar alterações que se sobrepõem. Um PUT, mesmo idempotente, pode substituir uma alteração mais recente quando a representação enviada está desatualizada.
Quando o contrato oferece controle de versão, o cabeçalho ETag, devolvido na consulta, identifica a versão lida, e o cabeçalho If-Match, enviado na alteração, condiciona a operação a essa versão. O código 412, de condição não atendida, indica que o registro mudou depois da leitura. O caminho é consultar o estado atual e rever a alteração, e não reenviar o mesmo conteúdo. Nem toda API oferece esse controle.
No suporte
Diante do código 405, de método não permitido, convém comparar o método e o caminho com o contrato. O 405 indica que o método é conhecido, mas não é aceito para aquele recurso, e a resposta deve trazer o cabeçalho Allow, com os métodos aceitos.
Para guardar
- O método expressa a intenção, e o contrato define o comportamento de cada operação.
- O GET consulta, o POST cria ou executa, o PUT substitui, o PATCH altera parte e o DELETE remove.
- A criação, o aceite e a aprovação do negócio são resultados diferentes.
- O cancelamento de um pagamento é uma operação própria, e não um DELETE.
- O controle de versão evita que uma alteração antiga substitua uma mais recente.
Um PUT enviado só com o e-mail deixou vazio o telefone do cliente. O que esse resultado sugere?
Que a operação trata a chamada como uma substituição completa e aplica um valor vazio ou padrão aos campos omitidos. O contrato confirma esse comportamento, e a alteração parcial usa o mecanismo permitido, como o PATCH.
Um POST de cobrança recebeu o código 202. O pagamento terminou?
Não é possível concluir isso pelo código. O 202 informa que a requisição foi aceita para processamento, e a conclusão é acompanhada pela consulta ou pelo aviso previsto na integração.