O que as excelentes APIs têm em comum? [fechadas]

O que há nas ótimas APIs que as tornam ótimas? Eu acho que aderir ao mantra "faça uma coisa e faça bem" é um bom sinal e ser um bom mapeamento para o domínio do problema são importantes, mas o que as grandes APIs têm em comum?

Você deve ter cuidado para evitar adicionar novo vocabulário apenas por causa da sua API. Minhas APIs favoritas me explicam coisas no vocabulário que eu já entendo. Nesse sentido:

Não adicione abstrações demais sobre o que você está construindo. Mantenha simples.

Eu já tenho que pensar em meia dúzia de camadas de abstração. Não me faça pensar em camadas extras. Não me dê muitas coisas novas para aprender que não agregarão valor ao meu objetivo final. Por exemplo, evite usar sua própria classe de arquivo especial que funcione de maneira diferente do tipo de arquivo do idioma, apenas porque você acha que seu caminho é melhor do que o geralmente aceito. Siga a maneira geralmente aceita, pelo menos em suas interfaces, para melhor ou para pior.

Ficar com idéias concretas

Por exemplo, não tente esconder o fato de que a parte "modelo" da sua estrutura MVC é um front end para um banco de dados. Aproveite o vocabulário conhecido em torno de "bancos de dados". Eu sei o que são chaves estrangeiras. Eu sei o que são linhas e colunas. Fale comigo nestes termos.

Não abstraia o conhecimento essencial

Semelhante a trabalhar com idéias concretas. Não esconda o fato de que estamos lidando com arquivos, bancos de dados ou linhas nos bancos de dados. Eu sei essas coisas. Se eu estou lidando com um contêiner, como uma Lista, há uma boa chance de eu precisar conhecer a complexidade algorítmica de operações comuns. Você pode simplificar muito dizendo apenas que é uma "lista vinculada" ou uma "matriz". De repente, um enorme conjunto de idéias será aplicado ao que você está fazendo e tudo fará sentido de repente. Não crie seu próprio conjunto de idéias que preciso aprender quando já tiver um conjunto de terminologias rico e útil para aplicar ao problema.

Reduzir o número de termos que preciso no meu vocabulário

Se estou usando sua API para abrir um arquivo de imagem de qualquer tipo, não preciso pensar muito em pngs x gifs x jpgs. Você fará isso por mim. É sua competência principal, não minha. Tenho um entendimento vago de que você tem alguma mágica para fazer isso por mim.

Uma API útil tem o seguinte:

• Documentação concisa e completa. Se estou pesquisando como implementar uma tarefa, sou capaz de descobrir se a API tem capacidade para fazê-lo em alguns minutos. Isso é obtido pela brevidade do texto e pelo layout do recurso. A documentação fornece exemplos de como usá-lo e também não faz suposições sobre os leitores.
• Uma comunidade grande e ativa. Fico feliz quando encontro fóruns, canais de IRC, listas de discussão etc. com participantes ativos dispostos a ajudar os novos. Entendo que esse geralmente é o caso de projetos maiores, mas ainda assim, seria algo pelo qual nos empenharíamos.
• Consistência. Na verdade, quando estou usando a API, não quero ficar chocado quando chamo um método ou descubro que esse método Xé completamente diferente da convenção definida pelo restante da API.

Ótimas APIs têm ótima documentação.

• Faça uma coisa e faça bem.
• Fácil de usar, difícil de usar indevidamente.
• Fácil de estender.
• Bem documentado.
• Estilo consistente.

Esta pergunta é abordada em "Design prático da API: Confissões de um arquiteto Java Framework" por Jaroslav Tulach da equipe do NetBeans.

A interface útil mais simples e boas convenções de nomenclatura.