Qu'est-ce que les excellentes API ont en commun? [fermé]

Qu'est-ce qui fait que les API sont géniales? Je pense qu'adhérer au mantra «faites une chose et faites-le bien» est un bon signe et être une bonne mise en correspondance avec le domaine problématique est important, mais qu'est-ce que les excellentes API ont en commun?

Vous devez faire attention à ne pas ajouter de nouveau vocabulaire juste pour le bien de votre API. Mes API préférées m'expliquent des choses dans un vocabulaire que je comprends déjà. Dans ce sens:

N'ajoutez pas trop d'abstractions en plus de ce que vous construisez. Rester simple.

Je dois déjà penser à environ une demi-douzaine de couches d'abstraction. Ne me faites pas penser à des couches supplémentaires. Ne me donnez pas trop de nouvelles choses à apprendre qui n'ajouteront pas de valeur à mon objectif final. Par exemple, évitez d'utiliser votre propre classe de fichier spéciale qui fonctionne différemment du type de fichier de la langue, car vous pensez que votre chemin est meilleur que le chemin généralement accepté. Restez fidèle à la manière généralement acceptée, au moins dans vos interfaces, pour le meilleur ou pour le pire.

Restez avec des idées concrètes

Par exemple, n'essayez pas de cacher le fait que la partie "modèle" de votre framework MVC est un frontal pour une base de données. Profitez du vocabulaire bien connu entourant les «bases de données». Je sais ce que sont les clés étrangères. Je sais ce que sont les lignes et les colonnes. Parlez-moi en ces termes.

N'abstenez pas les connaissances essentielles

Similaire à travailler avec des idées concrètes. Ne cachez pas le fait que nous traitons des fichiers ou des bases de données ou des lignes dans les bases de données. Je connais ces choses. Si j'ai affaire à un conteneur, comme une liste, il y a de fortes chances que j'ai besoin de connaître la complexité algorithmique des opérations courantes. Vous pouvez simplifier cela en me disant simplement que c'est une "liste chaînée" ou un "tableau". Un énorme ensemble d'idées sera soudainement mis à contribution dans ce que vous faites et tout cela aura soudain du sens. Ne créez pas votre propre ensemble d'idées que je dois apprendre quand je serai déjà venu avec un ensemble riche et utile de terminologie à appliquer au problème.

Réduire le nombre de termes dont j'ai besoin dans mon vocabulaire

Si j'utilise votre API pour ouvrir un fichier image de tout type, je ne devrais pas avoir à penser à pngs vs gifs vs jpgs. Tu feras ça pour moi. C'est votre compétence de base, pas la mienne. J'ai une vague compréhension que vous avez de la magie pour le faire pour moi.

Une API utile présente les éléments suivants:

• Documentation concise et approfondie. Si je cherche à implémenter une tâche, je peux savoir si l'API a la capacité de le faire, en quelques minutes. Ceci est réalisé par la brièveté du texte et la disposition de la ressource. La documentation fournit des exemples sur la façon de l'utiliser et ne fait aucune hypothèse sur le lectorat.
• Une grande communauté active. Je suis ravi de trouver des forums, des canaux IRC, des listes de diffusion, etc. avec des participants actifs prêts à aider les nouveaux gars. Je comprends que c'est généralement le cas pour les grands projets, mais ce serait quand même quelque chose à rechercher.
• Cohérence. Quand je suis en fait en utilisant l'API, je ne veux pas être choqué de quelque manière que quand je l' appelle une méthode, ou de découvrir cette méthode Xest tout à fait différent de l'ensemble de la convention par le reste de l'API.

Les bonnes API ont une excellente documentation.

• Faites une chose et faites-la très bien.
• Facile à utiliser, difficile à mal utiliser.
• Facile à étendre.
• Bien documenté.
• Style cohérent.

Cette question est abordée dans "Practical API Design: Confessions of a Java Framework Architect" par Jaroslav Tulach de l'équipe NetBeans.

L'interface utile la plus simple et les bonnes conventions de dénomination.