Meilleures pratiques et directives pour la conception d’une API

Quelles sont les lignes direcsortingces et les meilleures pratiques auxquelles je peux adhérer lors de la conception d’une API? Au ssortingct minimum, je sais qu’une API doit être facile à utiliser et flexible. Malheureusement, ces termes peuvent être plutôt subjectifs, alors je cherchais des directives concrètes concernant la conception de bonnes API.

Joshua Bloch – Comment concevoir une bonne API et pourquoi c’est important

Les exemples sont en Java mais vous pouvez quand même dessiner des parallèles. Puisque vous n’avez pas mentionné de technologie spécifique; Je suppose que vous ne voulez pas de solutions de niche.

En tant que personne qui doit consumr des tonnes d’API …

Veuillez écrire votre API de manière cohérente:

  1. Dénomination cohérente au sein même de l’API. Utilisez des verbes, des noms, des mots-clés EXACTEMENT dans le même style.

  2. Conformément à l’environnement cible, il sera utilisé. Si .NET, consultez les directives de dénomination de Microsoft.

  3. Concepts cohérents Modèle d’usine? Modèle de constructeur? Méthodes statiques Interfaces? Choisissez-en un et respectez-le. VRAIMENT. Il n’existe pas de petite exception à la règle. Il se dégagera comme un gros pouce douloureux. Plus d’une exception? Votre API est de plus en plus amateur.

En voici une autre: la spécificité.

  1. Les classes de base que je peux implémenter, si vous choisissez de les fournir, doivent avoir peu de fonctions bien définies à mettre en œuvre. Ne me dites pas “GetData ()” renvoie un “object []” et attendez-moi à ce que je l’implémente, déterminez pourquoi je dois le convertir en chaîne de caractères [], puis déboguez pourquoi il est appelé 20 fois. Il est préférable d’avoir DataPoint [] GetChartData (), ssortingng [] GetLabelData (), etc. et de me laisser choisir ceux que je devrais implémenter.

  2. S’il vous plaît ne devenez pas long avec des noms: PostRenderColorWheelModifyHSVBaseHandler. Vous pouvez souvent réorganiser les choses super-spécifiques dans un nom plus générique + parameters.

  3. Les parameters de chaîne sont un no-no! Utilisez des énumérations. Je ne veux pas utiliser un Handler comme

    PostRenderHandler (“ColorWheel”, “HSV”, someDelegate);

Je préférerais plutôt une énumération que je peux enquêter:

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

Man, je pourrais continuer … Le pouvoir de ce gars Josh Bloch – des API bien écrites peuvent être vraiment géniales … les mauvaises peuvent être très douloureuses.

Il y a une bonne présentation sur ce sujet de 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.

Ceci est un lien de Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

Il existe également ce livre: Framework Design Guidelines: conventions, expressions idiomatiques et modèles pour les bibliothèques .NET réutilisables

Je pense que votre question n’aura pas de place dans la quantité d’informations que vous donnez. J’ai mis plusieurs liens en tapant ‘design api’ dans google, et sur la première page obtenez-les qui ont l’air assez bien

http://web.archive.org/web/20151229055009/http://lcsd05.cs.tamu.edu/slides/keynote.pdf

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

http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf