Contratos vencem APIs espertinhas

O modo de falha

APIs pequenas costumam ser over-designed no lugar errado. A camada de transporte fica "esperta", mas o contrato continua vago o bastante para cada cliente ter que redescobrir o que o sistema realmente quer dizer.

O que eu prefiro

Eu prefiro colocar no ar:

• formato de resposta estreito,
• validação ou schema compartilhado,
• envelope de erro previsível,
• e docs que mostram o mesmo contrato que o código reforça.

Por que isso importa

Quanto mais fácil o contrato é de ler, mais fácil ele é de testar, revisar e mudar sem quebra escondida. Esse sinal vale mais do que uma camada extra de abstração nas rotas.

Sinal de portfólio

Quando eu mantenho um projeto backend público, eu quero que o contrato seja uma das primeiras coisas em que outro engenheiro consiga confiar.