Versionnement et dépréciation

La version fait partie du chemin : /api/v1/…, /api/v2/…. Jamais un en-tête, jamais un paramètre de requête — une version visible dans l'URL est une version que vous pouvez épingler, journaliser et rechercher.

La garantie

À l'intérieur d'une version publiée, nous pouvons ajouter : un nouvel endpoint, un nouveau champ optionnel dans une réponse, un nouveau paramètre optionnel. Nous ne retirerons pas un champ, n'en renommerons pas, ne resserrerons pas un type et ne changerons pas un code de statut. Chacun de ces cas est une rupture, et une rupture donne lieu à une nouvelle version, jamais à la modification de l'existante.

C'est vérifié dans notre chaîne d'intégration : un diff de contrat tourne à chaque changement et bloque la construction dès qu'une rupture apparaît sur une version déjà publiée. C'est un garde-fou, pas une intention.

Écrivez donc votre client de façon à ignorer les champs inconnus. Un parseur strict qui les rejette transforme notre ajout non ruptif en panne chez vous.

Versions en parallèle

v1 et v2 d'un même endpoint sont servies simultanément et atteignent la même logique sous-jacente ; seul le contrat public diffère. Migrez quand cela vous arrange, endpoint par endpoint — il n'y a pas de bascule générale.

En-têtes de dépréciation

Quand une version part en fin de vie, ses réponses l'annoncent. Les en-têtes sont présents sur toutes les réponses de l'endpoint, erreurs comprises — vous n'avez pas besoin d'un appel réussi pour le découvrir.

Les deux formats de date diffèrent volontairement — Deprecation porte une date de champ structuré (@epoch), Sunset une HTTP-date. Analysez chacun selon son format plutôt que de les supposer identiques.

Deprecation est la date à laquelle l'endpoint est devenu déprécié ; Sunset celle à laquelle il cesse d'être servi. Entre les deux, l'endpoint fonctionne exactement comme avant.

Qu'en faire

Journalisez ces en-têtes. Une intégration qui les ignore fonctionne jusqu'à la seconde où elle s'arrête, et la date de sunset est précisément l'avertissement qui vous avait été donné.

Un dispositif efficace : une alerte à la première réponse portant Deprecation, et une alerte plus forte à l'approche du Sunset. Le chemin de migration est toujours documenté à l'URL du Link lorsqu'il est publié.

Une réserve : ces en-têtes sont écrits par l'endpoint lui-même. Un 401 dû à un jeton expiré — rejeté avant d'atteindre l'endpoint — ne porte donc aucune annonce. Lisez-les sur des appels réellement authentifiés.