Apprendre
Versionnage
La version fait partie de l’URL, et une version qui va disparaître vous le dit dans ses propres en-têtes de réponse.
La version actuelle
v1 est la version actuelle et la seule prise en charge. Épinglez votre intégration à une version explicite dans le chemin ; il n’existe pas d’alias sans version, et il n’y en aura pas.
La politique
Quand une nouvelle version majeure sort, la précédente continue de fonctionner à côté d’elle. Le retrait est annoncé au moins 183 jours à l’avance, et chaque compte dont une clé a appelé la version sortante au cours des 90 jours précédents reçoit un courriel direct.
183 jours de préavis sont un plancher, pas un objectif. Ce délai existe pour qu’une intégration à laquelle personne n’a touché depuis un an dispose encore de deux trimestres pour réagir après l’arrivée du premier courriel.
Ce qui compte comme changement cassant
Les changements cassants imposent une nouvelle version. Tout le reste est livré dans la version actuelle, et c’est pour cela que votre client doit tolérer les ajouts.
Impose un changement de version
- Supprimer ou renommer un champ de réponse
- Durcir la validation d’un paramètre existant
- Changer le code d’erreur renvoyé par une condition
Livré sans changement de version
- Ajouter un champ optionnel de requête ou de réponse
- Ajouter une valeur à une énumération existante
- Ajouter un nouveau point de terminaison
Deux obligations pour votre client
Ignorez les champs que vous ne reconnaissez pas au lieu de rejeter la réponse, et traitez les valeurs d’énumération inconnues avec une branche par défaut au lieu de lever une exception. SMSend compte sur les deux quand il livre des changements non cassants — un client qui plante sur une nouvelle valeur de statut cassera un jour où rien n’avait été annoncé.
En-têtes de dépréciation
Tant qu’une version est en cours de retrait, chaque réponse qu’elle sert porte la date de sa dépréciation, la date à laquelle elle cessera de fonctionner et un lien vers l’avis.
Ces en-têtes n’apparaissent jamais sur la version actuelle. Les apposer sur une version qui ne va nulle part apprendrait à tous les clients à les ignorer, ce qui est exactement ce que vous ne voulez pas le jour où ils comptent.
Appeler une version qui n’existe pas
Une requête vers une version non prise en charge renvoie 400 avec UNSUPPORTED_VERSION et la liste des versions qui fonctionnent — jamais un simple 404. Un 404 se lit comme « vous vous êtes trompé d’URL » et envoie les gens chercher une faute de frappe au lieu de l’avis de dépréciation qu’ils ont manqué.