Design não é só sobre aparência e sentimento. Design é como funciona - Steve Jobs

Quando as API´s já estão prontas, mudanças são difíceis, cara e demandam tempo. Pior ainda, realizar correções e mudanças em APIs que já estão no cliente. O planejamento permite programar todos os detalhes, de forma a iterar várias propostas e possibilidades e executar análises hipotéticas. Enfim, mudanças no início do planejamento de uma API são mais baratas ;)

Mesmo assim, você ainda vai encontrar mais desenvolvedores codificando suas APIs do que planejando elas. As APIs, são sempre consideradas para consumo de maquinas e não para uma interface orientada ao usuário, como resultado disso as organizações não investem muita atenção e recursos para criar um processo de desenvolvimento de APIs.  Contudo, como hoje as arquiteturas de micro-serviços estão conquistando o mundo, as APIs estão começando a parecer mais como um produto do que uma tecnologia. Nesta visão estão proporcionando mais funcionalidades para os usuários finais.

Muitas APIs RESTful projetadas hoje não passam de navegadores de objetos que fornecem representações internas dos objetos de domínio/negócios sobre protocolos HTTP/S como uma camada de transporte. Então, como você pode fazer o melhor projeto de APIs, como você pode garantir que todas as APIs que você desenvolver seguem padrões consistentes, como você pode garantir que novos integrantes da equipe não reinventem a roda criando projetos de  APIs que o resto do time já está saturado. Se você ler estas questões de novo, você vai descobrir que está faltando o processo de planejamento de APIs similar ao que os designers de UX empregam e esse é o tipo de problema que eles resolvem diariamente em suas rotinas.

Parar criar um ótimo projeto de API você deve responder as seguintes perguntas ao projetá-la:

Util: A API é útil do pondo de vista do usuário final?

Utilizável: A API pode ser usada de forma rápida por um desenvolvedor e fornecer funcionalidades fáceis de usar?

Desejável: A funcionalidade fornecida pela API é algo que gera vontade de utilizar por parte dos desenvolvedores e usuários finais?

Localizável: A documentação da API pode ser encontrada facilmente e os desenvolvedores podem começar a usá-la imediatamente?

Acessível: A API pode fornecer funcionalidade para usuários finais que possuem restrições/limitações técnicas ao consumi-la?

Credibilidade: Os dados fornecidos pela APIs são confiáveis?

Valor: A API contribui para os resultados da empresa e melhora a satisfação do cliente?