APIs REST: contratos claros, erros úteis e versionamento pragmático

Uma API é um produto: quem a consome precisa de previsibilidade. Isso começa com um contrato explícito — esquema de pedido e resposta, campos obrigatórios, formatos de data e paginação — antes de discutir frameworks.

Erros são documentação em tempo real. Mensagens genéricas «algo correu mal» em 500 escondem ação. Prefira códigos de erro estáveis (ex.: `INSUFFICIENT_FUNDS`), correlation id para suporte e 4xx quando o cliente pode corrigir o pedido.

Versionamento não precisa de v47 no URL no primeiro dia. Comece com mudanças compatíveis, deprecações anunciadas e janelas claras. Quando a quebra for inevitável, um prefixo `/v2` ou negociação por header, documentado, evita caos em apps já publicados nas lojas.

Ferramentas como OpenAPI ajudam a gerar SDKs e testes de contrato, mas o hábito de revisar breaking changes em PR é o que sustenta a confiança entre equipas.