Référence

Versions

Une seule version, v1, sous /v1. Elle ne fait que s’enrichir ; rien n’y change ni n’y disparaît sans un an de préavis.

Ce qui peut changer dans v1

Uniquement des changements additifs : nouvelles routes, nouveaux champs de requête facultatifs, nouveaux champs de réponse, nouvelles valeurs d’enum dans les réponses, nouveaux motifs d’erreur, nouveaux événements de webhook et champs de contenu. Écrivez des clients qui ignorent les champs inconnus et tolèrent les valeurs d’enum inconnues.

Un changement incompatible est une nouvelle version majeure (/v2) servie à côté de v1.

Dépréciation

Une route ou un champ peut être déprécié, jamais modifié sur place. Dès le jour de la dépréciation, chaque réponse qui y touche porte Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) et un Link vers son entrée du journal des modifications avec rel="deprecation". Elle continue de fonctionner au moins 365 jours ensuite.

Journalisez l’en-tête Deprecation ou déclenchez une alerte dessus et vous serez informé de chaque dépréciation bien avant que cela compte. Chacune figure dans le journal des modifications.

Contenus des webhooks

Les contenus des webhooks sont versionnés par date (2026-09-01 aujourd’hui). Chaque endpoint conserve la version de contenu avec laquelle il a été créé : un futur changement incompatible d’un contenu n’atteint donc que les endpoints qui l’adoptent.