API REST com Spring MVC

Uma aplicação web sempre acaba tendo clientes que não são navegadores. Um aplicativo mobile, um painel em React, um script de importação noturno, um parceiro que sincroniza o próprio catálogo. Nenhum desses clientes quer HTML: eles querem dados e uma forma confiável de saber se a operação deu certo.

O reflexo comum é devolver JSON a partir dos controladores existentes e considerar o trabalho concluído. É aqui que nascem as APIs mal projetadas, e o sintoma é sempre o mesmo: tudo responde 200. Um recurso inexistente devolve 200 com corpo null. Uma validação que falha devolve 200 com um campo "erreur" no JSON. Uma exceção devolve 200 com corpo vazio. O cliente não consegue mais decidir nada automaticamente; precisa inspecionar o conteúdo para adivinhar o que aconteceu, e cada cliente adivinha de um jeito diferente.

O código de status HTTP não é decoração: é o único canal que todos os clientes, todas as bibliotecas HTTP e todos os intermediários de rede entendem sem nenhuma convenção prévia. Um 404 é tratado corretamente por um cache, um 429 dispara uma nova tentativa em um cliente bem escrito, um 201 com um cabeçalho Location indica onde está o recurso criado. Devolver 200 para tudo é recusar-se a usar um protocolo pelo qual você já paga.