Versionnement d'API

Trois approches principales existent. Le versionnement par URI (/v1/, /v2/) est le plus courant : les clients spécifient explicitement la version dans chaque URL de requête. Simple et très visible, mais les routes que l'équipe doit maintenir en parallèle augmentent avec chaque version majeure. Le versionnement par en-tête (API-Version: 2024-01-01) maintient l'URL propre et permet un versionnement basé sur la date (le modèle de Stripe), où chaque version d'API est nommée d'après une date et les clients sont mis à niveau vers de nouvelles valeurs par défaut à l'occasion de l'anniversaire de leur compte. Le versionnement par paramètre de requête (?version=2) est le plus simple mais souvent considéré comme le moins propre. La plupart des API SaaS utilisent le versionnement par URI pour les API publiques. Quel que soit le mécanisme, les engagements clés envers les clients sont : combien de temps les anciennes versions seront-elles prises en charge ? (la norme de l'industrie est de 12 à 24 mois après la publication d'une nouvelle version) ; comment les 'breaking changes' (changements cassants) sont-ils définis et communiqués ? (une définition formelle de 'breaking change' évite les débats lors de la dépréciation) ; et quel est le chemin de migration ? (fournir des guides de migration clairs avec des exemples de code).

La dépréciation d'API est un événement lié à la confiance des clients — mal gérée, elle génère un sentiment négatif significatif même lorsque l'amélioration du produit sous-jacent est positive. Les meilleures pratiques pour la dépréciation d'API SaaS : annoncer la dépréciation 12 mois ou plus à l'avance (au minimum 6 mois pour les endpoints à faible utilisation) ; fournir une date de fin de vie ('sunset date') concrète (les délais de dépréciation ambigus créent une fausse sécurité) ; envoyer des notifications ciblées à chaque client utilisant activement l'endpoint déprécié (identifiable à partir des logs d'API — "Cher [Entreprise], nos registres montrent que vous appelez /v1/users — cet endpoint sera retiré le [date]. Voici comment migrer :") ; publier un guide de migration détaillé avec des exemples de code avant/après ; offrir un mode de compatibilité ou une période de 'shimming' où la nouvelle version traduit l'ancien schéma ; et créer un tableau de bord d'utilisation des endpoints dépréciés visible par les clients dans leurs paramètres d'administration, affichant leur utilisation et le temps restant.

Les dépréciations d'API génèrent de manière fiable des pics de tickets de support — les clients migrent à la dernière minute, des problèmes d'intégration apparaissent, et certains clients manquent entièrement la dépréciation. Stratégies d'atténuation : retirer ('sunset') par vagues plutôt qu'en une seule fois (désactiver pour 5% des clients affectés sélectionnés aléatoirement deux semaines avant le retrait complet, afin que les problèmes apparaissent avec un volume gérable avant l'impact total) ; renforcer le support pour la fenêtre de dépréciation (planifier des heures d'agent supplémentaires dans les deux semaines précédant et suivant la date de retrait) ; pré-construire une macro Zendesk avec le guide de migration et les solutions d'erreurs courantes, permettant une résolution rapide au premier contact par les agents de niveau 1 sans escalade vers l'ingénierie ; créer une vue Zendesk dédiée "API Migration" afin que ces tickets soient triés par vos agents les plus techniquement compétents ; et publier une mise à jour de statut en temps réel sur votre page de statut développeur pour le jour du retrait, avec une surveillance des pics d'erreurs liés à la migration.