Meilleures pratiques et lignes directrices pour la conception d'une API

Question

Quelles sont les lignes directrices et les meilleures pratiques à respecter lors de la conception d'une API ? Au minimum, je sais qu'une API doit être facile à utiliser et flexible. Malheureusement, ces termes peuvent être assez subjectifs, c'est pourquoi je cherchais des directives concrètes pour une bonne conception d'API.

Answer 1

J'ai trouvé que ce qui suit valait la peine d'être regardé Joshua Bloch - Comment concevoir une bonne API et pourquoi c'est important

Les exemples sont en Java, mais vous pouvez néanmoins établir des parallèles. Puisque vous n'avez pas mentionné de technologie spécifique, je suppose que vous ne voulez pas de solutions de niche.

Answer 2

En tant que personne qui doit consommer des tonnes d'API...

Veuillez rédiger votre API de manière cohérente :

1. Nommage cohérent au sein de l'API elle-même. Utilisez les verbes, les noms et les mots-clés EXACTEMENT dans le même style.

2. Cohérent avec l'environnement cible dans lequel il sera utilisé. S'il s'agit de .NET, consultez les directives de dénomination de Microsoft.

3. Des concepts cohérents. Le modèle Factory ? Modèle de constructeur ? Méthodes statiques ? Interfaces ? Il suffit d'en choisir un et de s'y tenir. VRAIMENT. Il n'y a rien de tel qu'un petit exception à la règle. Elle se distinguera comme un gros pouce endolori. Plus d'une exception ? Votre API est de plus en plus amateur.

En voici un autre : La spécificité.

1. Les classes de base que je peux mettre en œuvre, si vous choisissez de les fournir, doivent avoir des fonctions peu nombreuses et bien définies à mettre en œuvre. Ne me dites pas que "GetData()" renvoie un "objet[]" et attendez de moi que je l'implémente, que je comprenne pourquoi je dois le convertir en une chaîne[], puis que je débogue pourquoi il est appelé 20 fois. Il est bien mieux d'avoir DataPoint[] GetChartData(), string[] GetLabelData(), etc. et de me laisser choisir ceux que je dois implémenter.

2. S'il vous plaît, ne vous embarrassez pas de noms : PostRenderColorWheelModifyHSVBaseHandler. Vous pouvez souvent refactoriser des choses super spécifiques en un nom + des paramètres plus génériques.

3. Les paramètres de type chaîne sont à proscrire ! Utilisez des énumérations. Je ne veux pas utiliser un Handler comme

   PostRenderHandler("ColorWheel", "HSV", someDelegate) ;

Je préfèrerais avoir un enum sur lequel je puisse enquêter :

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

Bon sang, je pourrais continuer... La puissance de ce Josh Bloch - les API bien écrites peuvent être vraiment géniales... les mauvaises peuvent être vraiment pénibles.

Answer 3

Il existe un bonne présentation sur ce sujet par Joshua Bloch. La présentation utilise Java mais les idées sont indépendantes du langage. Une autre source (pdf) pour un aperçu rapide.

Answer 4

Il s'agit d'un lien de Microsoft : http://msdn.microsoft.com/en-us/library/ms229042.aspx

Il y a aussi ce livre : Lignes directrices pour la conception de cadres : Conventions, idiomes et modèles pour des bibliothèques .NET réutilisables

Answer 5

Je pense que votre question ne trouvera pas de réponse dans cet espace avec la quantité d'informations que vous donnez. J'ai mis plusieurs liens en tapant 'api design' dans Google, et sur la première page, j'ai obtenu ces liens qui semblent assez bons.

http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

http://chaos.troll.no/~shausman/api-design/api-design.pdf