Les meilleures pratiques et lignes directrices pour la conception d'une API

Question

Quelles sont les lignes directrices et les meilleures pratiques que je peux respecter lors de la conception d'une API? Au strict minimum, je sais qu'une API devrait être facile à utiliser et flexible. Malheureusement, ces termes peuvent être plutôt subjectifs, donc je cherchais des lignes directrices concrètes concernant la conception d'un API.

Answer 1

J'ai trouvé ce qui suit pour être vaut une montre Joshua Bloch - How To Design A Good API and Why it Matters

Les exemples sont en Java bien que vous puissiez toujours faire des parallèles. Puisque vous n'avez pas mentionné une technologie spécifique; Je suppose que vous ne voulez pas de solutions de niche.

Answer 2

Il y a un good presentation sur ce sujet de Joshua Bloch. La présentation utilise Java mais les idées sont indépendantes de la langue. Another source (pdf) pour un aperçu rapide.

Answer 3

Je pense que votre question ne sera pas répondu à cette quantité d'espace avec la quantité d'information que vous donnez. J'ai mis plusieurs liens de taper « design api » dans google, et sur la première page obtenir ces derniers qui semblent très bon

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

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

Answer 4

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

Il y a aussi ce livre: Framework Design Guidelines: Conventions, locutions et modèles réutilisables pour les bibliothèques .NET

Answer 5

Comme quelqu'un qui a consommer des tonnes des API ...

S'il vous plaît écrire votre API de manière cohérente:

1. Désignation cohérente dans l'API elle-même. Utilisez des verbes, des noms, des mots-clés dans exactement le même style.

2. Conformément à l'environnement cible, il sera utilisé. Si .NET, puis consultez les directives de nommage de Microsoft.

3. concepts cohérents. Modèle d'usine? Modèle Builder Méthodes statiques? Interfaces? Choisissez-en un et respectez-le. VRAIMENT. Il n'y a pas de petite exception à la règle. Il va sortir comme un gros pouce endolori. Plus d'une exception? Votre API est de plus en plus amateur.

En voici une autre: Spécificité.

1. Les classes de base que je peux mettre en œuvre, si vous choisissez de les fournir, devraient avoir des fonctions peu et bien définies pour mettre en œuvre. Ne me dites pas "GetData()" renvoie un "object []" et attendez que je l'implémente, comprenez pourquoi je dois le convertir en une chaîne [], puis déboguez pourquoi il est appelé 20 fois. Il est préférable d'avoir DataPoint [] GetChartData(), string [] GetLabelData(), etc. et laissez-moi choisir ceux que je devrais implémenter.

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

3. Les paramètres de chaîne sont un non-non! Utilisez les énumérations. Je ne veux pas utiliser un gestionnaire comme

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

Je préfère comme un ENUM je peux étudier:

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

Man, je pourrais continuer ... Le pouvoir de ce type Josh Bloch - API bien écrit peut être vraiment génial ... les mauvais peuvent être vraiment douloureux.