← REST APIs: integrar aplicações e diagnosticar falhas
02 / 12 · 40 MIN

Pedidos e resultados

Distingue aceitação técnica, conclusão e erro acionável.

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.

NA PRÁTICA

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

Leva esta ideia contigo

Liga cada resposta a uma decisão concreta do consumidor.

Criar conta

Referências