Cela dépend uniquement du type de stabilité que vous avez donné à vos utilisateurs et de la douleur que vous souhaitez causer à vos utilisateurs.
Idéalement, votre API utilise semver de sorte que toute modification importante entraîne l’incrémentation du numéro de version principal. En pratique, il est souhaitable de le faire presque jamais. Si votre API est installée via un gestionnaire de paquets, vous pouvez créer un nouveau nom de paquet après une modification radicale, de sorte qu'une mise à niveau simple ne provoque pas de conflits (par exemple, myapi2 v2.123.4
vs myapi3 v3.2.1
). Cela peut être inutile si votre gestionnaire de paquets prend en charge des dépendances de version plus strictes (par exemple, une spécification de dépendance comme ~v2.120
celle-ci n’inclut pas v3.*
), mais différents noms de paquet présentent l’avantage que les versions incompatibles peuvent être utilisées très facilement côte à côte. Même en utilisant semver, il peut être judicieux d'avoir une période de désapprobation.
Semver n'est pas toujours applicable. Ensuite, il est plus important de communiquer une politique de stabilité claire. Par exemple:
- Les fonctions expérimentales peuvent être supprimées sans préavis.
- Les fonctionnalités peuvent être supprimées pour des raisons de sécurité à tout moment.
- Les autres fonctionnalités ne seront supprimées
- … Après avoir été déconseillé dans une version publiée
- … Où cette version a au moins trois mois
- … Et sera marquée par une bosse dans la version majeure.
De telles stratégies fonctionnent particulièrement bien lorsque vous avez des mises à jour régulières, de sorte qu'une période de dépréciation, par exemple un an, est clairement définie.
En plus de marquer des parties de l'API comme étant déconseillées, vous devez largement faire connaître cette dépréciation. Par exemple:
- Avoir une section dans votre changelog sur les directions futures et les déprécations.
- Diffusez votre intention de déprécier avant d'exécuter la dépréciation et écoutez la communauté pour voir s'il y a des objections importantes.
- Communiquez quels avantages découleront de ces changements. Selon votre base d'utilisateurs, les bulletins d'information, les présentations, les articles de blog ou les communiqués de presse peuvent constituer des supports appropriés. Faire un tour «nous créons une nouvelle fonctionnalité géniale! (qui nécessite la suppression de cette ancienne fonctionnalité largement utilisée) ”est un peu moins frustrant que de supprimer une fonctionnalité sans contexte.
En ce qui concerne la période de dépréciation exacte à choisir, commencez par vérifier si vous devez respecter les contrats de support avec vos utilisateurs. Ces contrats peuvent vous obliger à maintenir la compatibilité pendant un certain temps. Sinon, envisagez tout impact en aval. Essayez de changer moins rapidement que les utilisateurs en aval afin qu'ils puissent traverser leur propre cycle de dépréciation. Les utilisateurs en aval mettront un certain temps à s’adapter à vos modifications. Par conséquent, vous ne devriez jamais avoir une période de dépréciation inférieure à un mois.