Conceito e mecanismo
Duas equipas podem alterar o mesmo recurso a partir de leituras diferentes. Um validador, como um ETag adequado a comparação forte, permite condicionar a escrita à versão observada. Se a condição falha, o consumidor precisa de obter estado atual e decidir como conciliar a intenção, em vez de remover a proteção e sobrescrever silenciosamente.
PATCH descreve uma modificação parcial cujo significado depende do media type. JSON Patch contém operações ordenadas, incluindo test; um número e o mesmo texto numérico não são valores equivalentes nesse teste. A atomicidade do documento de patch não constitui uma transação automática entre todos os serviços envolvidos no negócio.
Aplicação guiada
Num cenário fictício, o cliente perde a resposta depois de enviar uma criação. O timeout deixa o resultado desconhecido: o servidor pode ter concluído. Antes de repetir, usa o contrato de idempotência ou consulta uma referência de operação existente.
Uma chave de idempotência só funciona se o servidor definir armazenamento, âmbito, concorrência e retenção. A documentação Stripe é um exemplo de contrato de fornecedor, não uma regra universal para qualquer API. Alterar a chave em cada tentativa pode transformar repetição em nova operação.
Mantém a mesma intenção e payload quando o contrato exige isso; depois de expirar a retenção, concilia o resultado antes de assumir proteção.
Resposta perdida não equivale a operação não executada; uma nova tentativa precisa de preservar a identidade da intenção.
Armadilhas comuns
Timeout como falha sem efeito; chave nova em cada retry; PATCH sempre idempotente; retirar If-Match para resolver conflito.
Tópicos relacionados: Recursos e contratos de API · Pedidos e resultados · Autorização e fronteiras
Controla separadamente concorrência de escrita e repetição de pedidos.
Referências
- Idempotent requests · Provider contract consulted 2026-09-30; not universal HTTP guarantee
- RFC9110 HTTP Semantics · RFC9110 June 2022
- RFC5789 PATCH Method for HTTP · RFC5789 March 2010
- RFC6902 JavaScript Object Notation JSON Patch · RFC6902 April 2013