APRENDER. PRATICAR. EVOLUIR.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ência: RFC9457 Problem Details for HTTP APIs · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30