web-dev-qa-db-fra.com

Meilleures pratiques et directives pour la conception d'une API

Quelles sont les directives et les meilleures pratiques auxquelles je peux adhérer 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 plutôt subjectifs, donc je cherchais des directives concrètes concernant une bonne conception d'API.

apiapi-design
92
Vivin Paliath

J'ai trouvé ce qui suit mérite une montre Joshua Bloch - Comment concevoir une bonne API et pourquoi cela importe

Les exemples sont en Java cependant, mais vous pouvez 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.

60
Gishu

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

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

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

  2. Conformément à l'environnement cible dans lequel 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? Des interfaces? Choisissez-en un et respectez-le. VRAIMENT. Il n'y a pas d'exception small à la règle. Il ressortira comme un gros pouce endolori. 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, devraient avoir peu de fonctions bien définies à implémenter. Ne me dites pas que "GetData ()" renvoie un "objet []", puis attendez-vous à ce 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 de me laisser choisir ceux que je dois implémenter.

  2. S'il vous plaît ne soyez pas idiot avec les noms: PostRenderColorWheelModifyHSVBaseHandler. Vous pouvez souvent refaçonner des choses super spécifiques en un nom + paramètres plus génériques.

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

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

Je préfère de beaucoup une énumération sur laquelle je peux enquêter:

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

Mec, je pourrais continuer ... Pouvoir à ce gars de Josh Bloch - les API bien écrites peuvent être vraiment géniales ... les mauvaises peuvent être vraiment douloureuses.

32
Jeff Meatball Yang

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

12
Csaba_H

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

Il existe également ce livre: Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

9
Klinger

Je pense que votre question n'aura pas de réponse dans cette quantité d'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, obtenez ceux qui semblent assez bons

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

3
Romain Hippeau