Conceito e mecanismo
O método, os headers e o corpo comunicam intenção e representação. Content-Type identifica o conteúdo enviado; Accept descreve preferências para a resposta. Escolher um método só pelo nome de uma função interna reduz a clareza do contrato.
Uma operação de leitura não deve esconder uma ação comercial irreversível que um intermediário pode repetir. O resultado HTTP deve corresponder ao que a camada que respondeu sabe. Uma resposta de aceitação assíncrona não prova conclusão do trabalho.
Define como obter estado, como distinguir falha final de espera e quando o consumidor deve deixar de consultar.
Aplicação guiada
Num exercício fictício, a criação de um pedido devolve 202 e uma referência para acompanhar processamento. O painel marca imediatamente o pedido como liquidado, embora o worker ainda não o tenha tratado. A correção está em modelar estados e verificar o resultado final, mantendo a referência para diagnóstico.
Para erros, Problem Details permite uma estrutura consistente e extensões específicas. O status no corpo não substitui o código real da resposta. Usa identificadores de ocorrência e mensagens úteis, sem stack traces ou conteúdo sensível.
O cliente deve tratar categorias e tipos de erro definidos no contrato, evitando depender de uma frase traduzida que pode mudar entre versões.
Aceite, em processamento e concluído são estados diferentes no acompanhamento da operação.
Armadilhas comuns
202 como conclusão; erro dentro de 200 como contrato transparente; mensagens humanas como identificadores estáveis.
Tópicos relacionados: Recursos e contratos de API · Concorrência e repetição · Autorização e fronteiras
Liga cada resposta a uma decisão concreta do consumidor.
Referências
- RFC9457 Problem Details for HTTP APIs · RFC9457 July 2023
- RFC9110 HTTP Semantics · RFC9110 June 2022