As APIs são o contrato entre o seu sistema e os seus consumidores. Uma API bem desenhada facilita a integração. Uma mal desenhada cria fricção que se acumula com o tempo.
Nomenclatura consistente de recursos
Use nomes no plural para recursos (/users, /orders). Aninhe recursos para mostrar hierarquia (/orders/123/items). Use parâmetros de query para filtragem e paginação. Evite verbos nos URLs — os métodos HTTP já expressam a ação.
Versionamento
Coloque um prefixo de versão no caminho da API (/v1/orders). Versione quando fizer mudanças breaking no contrato. Adições não-breaking (novos campos, novos endpoints) não requerem uma nova versão.
Respostas de erro
Retorne estruturas de erro consistentes. Inclua um código de erro legível por máquina, uma mensagem legível por humanos e um trace ID para debugging.
Use códigos de status HTTP padrão. 400 para erros de validação, 404 para não encontrado, 409 para conflitos, 500 para erros de servidor.
Paginação
Pagina sempre os endpoints de lista. Use paginação baseada em cursor para grandes conjuntos de dados. Retorne cursores next e previous na resposta para que os clientes não construam URLs.
Validação
Valide a entrada no limite da API. Retorne mensagens de erro detalhadas para cada campo inválido. Nunca confie na entrada do cliente, mesmo que venha do seu próprio frontend.