API en développement: l'équilibre entre les nouvelles fonctionnalités et compatibilité arrière

Question

Je travaille maintenant sur une API pour les développeurs caractéristique de notre produit.

La première version a été libérée et il a un petit nombre d'utilisateurs pour le moment. Depuis que j'ai commencé à développer sa deuxième version, certaines parties ont été retravaillées, certaines parties ont été supprimées pour rendre l'API plus élégante et plus claire.

Mais le déploiement de la 2ème version peut être pénible pour les anciens utilisateurs. Notre département marketing prévoit d'améliorer notre produit API, d'ajouter plus de fonctionnalités.

Comment dois-je construire le système, donc
1) nous ne serions pas contraints à la « ancienne version » pour ajouter de nouvelles fonctionnalités intéressantes
2) utilisateurs de l'API actuels ne seront pas satisfaits parce que Si les produits API doivent être testés dans un bac à sable pendant une période assez longue avant la sortie publique, il n'y aura pas de modifications significatives de la nécessité de retravailler leurs systèmes afin de se conformer à l'API modifiée

dans la spécification?

Answer 1

Lorsque vous devez apporter des modifications à l'API qui a déjà des utilisateurs, le meilleur moyen est probablement de déprécier les anciens appels API et d'encourager l'utilisation des nouveaux appels. La suppression de la capacité des anciens appels d'API casserait probablement la fonctionnalité de l'ancien code, de sorte que certains développeurs utilisant votre "ancienne" API pourraient être quelque peu insatisfaits.

Si votre langage permet d'indiquer que certaines fonctionnalités ont été déconseillées, cela peut indiquer aux utilisateurs d'arrêter d'utiliser les anciens appels API et de passer à de nouveaux appels. En Java, le @deprecated javadoc tag peut fournir des notes dans la documentation indiquant qu'une fonction a été abandonnée ou, à partir de Java 5, le @Deprecated annotation peut être utilisé pour élever les avertissements de compilation sur les appels aux fonctions d'API obsolètes. Il serait également judicieux de fournir quelques conseils et astuces sur la migration de l'ancienne API vers la nouvelle API afin d'encourager les utilisateurs à utiliser la nouvelle méthode d'interaction avec l'API. Ayant des exemples et des exemples de code sur quoi faire et quoi ne pas faire, les utilisateurs de l'API seraient capables d'écrire du code selon la nouvelle façon préférée. Il va être difficile de changer une API publique, mais avec un certain soin apporté à la transition de l'ancienne à la nouvelle, je crois que la quantité de douleur infligée aux utilisateurs de l'API peut être atténuée à un certain niveau. ampleur.

Voici un article sur How and When to Deprecate APIs de Sun, qui pourrait fournir plus d'informations sur le moment où il serait approprié de déprécier des parties d'API.

Aussi, merci à David Schmitt qui a ajouté que le Obsolete attribute dans .NET est similaire à l'annotation @Deprecated en Java. (Malheureusement, la modification a été écrasé par mon édition, que nous étions tous les deux éditons cette réponse en même temps.)

Answer 2

Il est un équilibre, vous devrez frapper avec votre communauté:

• Gardez anciennes fonctions pour aeons et vous allez vous retrouver avec l'API Win32 (30000 fonctions publiques )?Réécrire l'API tout le temps, et vous pouvez obtenir quelque chose de similaire à .NET, où une nouvelle révision sort de temps en temps (1.0, 2.0, 3.0, 3.5 ...) et rompt les programmes existants ou introduit de nouvelles et l'amélioration des moyens de faire UIs etc.)

Si la communauté est tolérante du changement et ouvert à l'expérimentation, vous vous efforcerez pour une API actuelle maigre, et je sais que certains casse, alias pourriture bits, résultera. Si, d'un autre côté, la communauté a des tonnes de code hérité et aucune ressource ou envie de l'amener à la dernière version, vous devez garder la compatibilité ascendante ou tout leur matériel ne fonctionnera tout simplement pas sur la nouvelle API.

---

Note à l'une des autres réponses: API désobligeantes est un moyen souvent utilisé pour indiquer quelles fonctions sont « à la sortie », mais aussi longtemps qu'ils travaillent, de nombreux développeurs les utilisera même dans le nouveau code parce que ce sont les fonctions auxquelles ils sont habitués. Il y a très peu de développeurs éclairés qui ont à la fois la conscience de réellement tenir compte des avertissements «obsolètes» et le temps de rechercher le code pour d'autres instances de l'ancienne API et de les mettre à jour.

Answer 3

Microsoft est assez connu pour sa rétrocompatibilité. L'une des choses qu'ils ont fait était de garder tous les anciens appels obsolètes, puis d'en ajouter de nouveaux que les nouveaux programmes pourraient utiliser pour accéder aux fonctionnalités améliorées qui ne pouvaient pas fonctionner dans l'ancienne API.

Vous n'avez pas spécifié le langage de programmation que vous utilisez, mais .NET et Java disposent d'un mécanisme permettant de marquer certains appels d'API comme obsolètes. Si la rétrocompatibilité est très importante pour vous, vous pouvez choisir le même itinéraire.

Answer 4

La rétrocompatibilité devrait être la valeur par défaut. La seule raison pour laquelle vous devez compromettre ce principe est lorsque l'API est en quelque sorte non sécurisée, ce qui force les utilisateurs à adopter des méthodes plus sécurisées.

Answer 5

Idéallement, les applications écrites dans votre API d'origine continueront à fonctionner avec la nouvelle version.

Une façon d'ajouter de nouvelles fonctionnalités tout en s'assurant que les anciennes applications continuent à s'exécuter est d'avoir deux versions d'un appel d'API. Par exemple, supposons que vous ayez actuellement une fonction Foo qui prend 2 paramètres (arguments) dans l'API mais vous décidez que la nouvelle version devrait vraiment prendre 3 paramètres. Gardez Foo comme il est et ajoutez une nouvelle fonction Foo2 qui prend 3 paramètres.

que les utilisateurs peuvent continuer à façon le code contre Foo pour la compatibilité descendante ou utilisez la nouvelle fonction foo2 si elles ont besoin des nouvelles fonctionnalités.

Cette technique a été couramment utilisée par Microsoft pour les API Windows.