Projetar uma interface com a qual dá para conviver
Consistência antes da beleza
A mesma convenção de nomenclatura em cada rota, a mesma estrutura de resposta, o mesmo formato de data, a mesma estrutura de erro. Dez rotas consistentes são mais fáceis do que cinco brilhantes e cinco diferentes.
Retorne uma estrutura estável: um objeto envelope com dados e metadados, para poder adicionar campos sem quebrar.
Decisões que voltam para você
Paginação. Decida com antecedência — por offset ou por cursor — e suporte em cada lista. Listas sem paginação sempre crescem além do esperado.
Filtragem e ordenação. Definidas e documentadas, não um campo livre onde cada consumidor inventa regras.
Identificadores. Estáveis, não sequenciais e que não revelam informação de negócio no número.
Erros são parte do contrato
Um código de status correto, um identificador de erro fixo no qual ramificar a lógica, uma mensagem legível e um identificador de requisição para investigação. Uma interface que retorna texto livre diferente em cada erro obriga o consumidor a checar strings.
Indo mais fundo
Documente a interface a partir do próprio código para que a documentação não envelheça, e forneça um ambiente de teste com dados fictícios. E antes de publicar: faça alguém que não escreveu a interface implementar um cenário completo contra ela — cada pergunta que fizer é uma falha de design, não uma lacuna de entendimento.