Comment définissez-vous une bonne ou une mauvaise API?

Question

Arrière-plan:

Je suis dans une classe à mon université, appelé "Logiciel de Contraintes". Dans les premières conférences nous ont été d'apprendre à construire de bonnes Api.

Un bon exemple nous avons eu une très mauvaise fonction de l'API est le socket public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); en C#. La fonction reçoit 3 listes de sockets, et détruit l'utilisateur ont pour cloner toutes les prises avant de les nourrir dans l' Select(). Il dispose également d'un délai d'attente (en microsecondes) qui est un int, qui définit le temps maximum que le serveur peut attendre d'un socket. Les limites de ce qui est +/-35 minutes (parce que c'est un int).

---

Questions:

1. Comment définissez-vous une API le "mauvais"?
2. Comment définissez-vous une API de la "bonne"?

---

Points à considérer:

• Les noms de fonction qui sont difficiles à mémoriser.
• Les paramètres de la fonction qui sont difficiles à comprendre.
• Mauvaise documentation.
• Tout est tellement lié que si vous avez besoin de changer 1 ligne de code que vous aurez réellement besoin de changer des centaines de lignes dans d'autres endroits.
• Les fonctions qui détruisent leurs arguments.
• Mauvais évolutivité en raison de "caché" de la complexité.
• Il est nécessaire de l'utilisateur/dev construire des wrappers autour de l'API, de sorte qu'il peut être utilisé.

Answer 1

Dans la conception d'API, j'ai toujours trouvé cette conférence très utile:
Comment Concevoir une Bonne API et Pourquoi c'est important - par Joshua Bloch

En voici un extrait, je vous recommande la lecture de l'ensemble de la chose ou de regarder la vidéo.

II. Principes Généraux

• L'API Doit Faire Une Chose et le Faire Bien
  
• L'API Doit Être aussi Petite Que Possible, Mais Pas plus Petit
  
• La mise en œuvre ne Devrait Pas influer sur l'API
  
• Réduire l'Accessibilité de Tout
  
• Les noms de Matière–API est un Peu la Langue
  
• La Documentation Des Questions
  
• Document Religieusement
  
• Prendre en compte les Performances des Conséquences de l'API, les Décisions de Conception
  
• Effets de l'API, les Décisions de Conception sur les Performances sont Réels et Permanents
  
• L'API Doit Coexister Pacifiquement avec Plate-forme de

III. Conception De Classe

• Minimiser La Mutabilité
  
• Sous-classe Seulement Où il Fait Sens
  
• La conception et le Document de l'Héritage ou de l'Autre de l'Interdire

IV. Méthode De Conception

• Ne pas informer le Client de Tout Faire, le Module pourra Faire
  
• Ne Viole pas le Principe de moindre Étonnement
  
• L'échec Rapide de Signaler les Erreurs Dès que Possible Après qu'Ils se Produisent
  
• Fournir un Accès par programme à l'Ensemble des Données Disponibles dans la Forme d'une Chaîne
  
• Surcharge Avec Soin
  
• Utilisation Appropriée de paramètres et Types de Retour
  
• Utilisation Conforme Paramètre De La Commande Sur Les Méthodes
  
• Éviter Les Longues Listes De Paramètres
  
• Éviter les Valeurs de Retour de la Demande Exceptionnelle de Traitement

Answer 2

Vous n'êtes pas obligé de lire la documentation pour l'utiliser correctement.

Le signe d'une API géniale.

Answer 3

De nombreuses normes de codage et de longs documents et même des livres (le Cadre des lignes Directrices de Conception) ont été écrits sur ce sujet, mais une grande partie de cette aide seulement à un niveau assez faible.

Il y a aussi une question de goût. Api peut obéir à toutes les règles de ce que livret de règles, et encore sucer, en raison d'un respect servile divers en vogue idéologies. Une récente coupable est le patron de l'orientation, dans lequel Singleton Modèles un peu plus de initialisé les variables globales) et de l'Usine de Motifs (une façon de paramétrage de la construction, mais souvent mis en œuvre lorsqu'il n'est pas nécessaire) sont surexploitées. Dernièrement, il est plus probable que l'Inversion de Contrôle (IoC) et associée à une explosion du nombre de petits types d'interface qui ajoute redondant complexité conceptuelle de dessins.

Les meilleurs professeurs pour le goût de l'imitation (la lecture de beaucoup de code et d'Api, trouver ce qui fonctionne et ne fonctionne pas), l'expérience (faire des erreurs et apprendre d'elle) et la pensée (ne pas simplement faire ce qui est à la mode pour son propre bien, réfléchissez avant d'agir).

Answer 4

• Utile - il répond à un besoin qui n'est pas déjà rencontré (ou améliorer ceux qui existent)
• Facile à expliquer - la compréhension de base de ce qu'il ne devrait être simple à appréhender
• Suit un certain modèle d'objet de quelques domaine du problème ou du monde réel. Il utilise des constructions qui ont du sens
• Utilisation correcte de l'synchrone et asynchrone des appels. (ne pas bloquer pour des choses qui prennent du temps)
• Bon comportement par défaut - si possible, permettre l'extensibilité et de peaufinage, mais de fournir des valeurs par défaut pour tout ce qui est nécessaire pour les cas simples
• Exemple utilise et travail exemples d'applications. C'est probablement le plus important de tous.
• Excellente documentation
• Manger votre propre nourriture pour chien (le cas échéant)
• Une petite entreprise ou d'un segment de sorte qu'il n'est pas un énorme pollué l'espace. Maintenir la fonctionnalité des ensembles distincts et isolés avec peu de dépendances.

Il y a plus, mais c'est un bon début

Answer 5

Une bonne API permet au client de faire à peu près tout ce qu'ils doivent faire, mais ne les oblige pas à faire beaucoup de mindless occupé-travail. Des exemples de "stupides travail serait de l'initialisation des données de champs de structure, l'appel de plusieurs routines dans une séquence qui ne varie jamais, sans véritable code personnalisé entre les deux, etc.

Le moyen le plus sûr signe d'une mauvaise API est si vos clients veulent tous l'envelopper avec leur propre helper de code. Au moins, votre API ont fourni de l'aide de code. Le plus probable, il doit avoir été conçu pour fournir le plus haut niveau d'abstraction, les clients sont de roulement eux-mêmes sur leurs propres à chaque époque.