Versions et dépréciation

Ce qui reste stable en v1, ce qui peut changer et comment une dépréciation est annoncée.

La version dans l'URL

La version fait partie du chemin : /api/v1/.... La version 1 est stable.

Changements qui ne cassent pas la v1

De nouvelles routes, de nouveaux paramètres optionnels et de nouveaux champs dans les réponses.
De nouveaux codes d'erreur et de nouveaux types d'événements webhook.
De nouvelles valeurs dans une liste de valeurs comme un statut.

Écrivez votre client pour ignorer les champs qu'il ne connaît pas, et pour traiter par défaut un code d'erreur ou un type d'événement inconnu au lieu d'échouer.

Changements cassants

Un changement cassant n'est publié que dans une nouvelle version (/v2). La version précédente continue de fonctionner au moins 6 mois après l'annonce.

Annonce d'une dépréciation

Une route dépréciée continue de répondre normalement et ajoute des en-têtes standard à chaque réponse : Deprecation (RFC 9745), Sunset (RFC 8594) avec la date de fin quand elle est connue, et un en-tête Link vers la documentation de migration. Surveillez ces en-têtes dans votre client pour être prévenu tôt.

Deprecation: @1767225600
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Link: <https://example.com/developers/guides/versions>; rel="deprecation"; type="text/html"