Dépréciations

Comment une route s’en va

1. Annoncée. La route continue de répondre exactement comme avant pendant au moins 30 jours. Chaque réponse porte les en-têtes Deprecation, Sunset et Link, et la référence marque l’opération comme dépréciée, avec sa date de fin et son remplacement.
2. Fin de vie. À partir du jour de fin, la route répond 410 Gone, avec son remplacement dans le corps.
3. Oubliée. Au bout d’un an ou plus, la route répond 404 comme n’importe quelle adresse inconnue.

Une route de version 1 s’en va en général sous ses deux écritures à la fois, le chemin nu et /v1/. Un avis sur la version 1 ne couvre jamais /v2/.

Les en-têtes

Par exemple, une route de version 1 que /v2/validators/{id}/ remplace envoie ces en-têtes à côté de son corps habituel :

Deprecation: @1791763200
Sunset: Wed, 11 Nov 2026 00:00:00 GMT
Link: <https://api.taoswap.org/changelog/>; rel="deprecation"; type="text/html", </v2/validators/{id}/>; rel="successor-version"

• Deprecation (RFC 9745) : le moment où la dépréciation a été annoncée, sous forme d’horodatage UNIX après @, à minuit UTC ce jour-là.
• Sunset (RFC 8594) : minuit UTC le jour où la route cesse de répondre. Elle répond jusqu’à la veille incluse.
• Link : rel="deprecation" pointe vers le journal des changements, et rel="successor-version" donne la route de remplacement sous forme de modèle de chemin, quand il y en a une.

Surveillez ces en-têtes dans votre client, par exemple en journalisant un avertissement chaque fois qu’une réponse porte Deprecation.

Après la fin de vie

La route répond 410 Gone avec l’enveloppe d’erreur habituelle de l’API et le code ENDPOINT_REMOVED. Son detail donne le jour où elle s’est arrêtée (removed_on), son remplacement (replacement), ou null quand rien ne la remplace, et la raison (reason). Les trois en-têtes restent sur cette réponse.

Champs

Un champ peut quitter une route de la même façon : même préavis et mêmes annonces, mais sans en-tête, puisque la route elle-même reste. Le champ garde sa valeur jusqu’à la fin de vie, puis quitte la réponse.

Où suivre les annonces

• Le journal des changements, api.taoswap.org/changelog : chaque route et chaque champ en voie de suppression, avec le jour où il s’arrête, les jours restants, son remplacement et ce qu’il faut faire, chaque entrée avec son propre lien.
• Son jumeau JSON, api.taoswap.org/changelog.json : les mêmes entrées pour les scripts, plus la politique elle-même (sunset_window_days, tombstone_keep_days).
• Son flux Atom, api.taoswap.org/changelog.atom : abonnez-vous avec un lecteur de flux ou un bot.
• Discord : chaque avis est publié dans le canal #api-changelog du Discord de Kusanagi Ventures au moment de son annonce, de nouveau 7 jours avant la fin de vie (et 30 jours avant, quand le préavis est plus long), et le jour de la fin de vie.

Le journal des changements ne liste que ce qui s’en va. Les nouvelles routes et les nouveaux champs n’y sont pas annoncés.

Si une date de fin pose problème à votre intégration, dites-le sur Discord avant qu’elle ne passe.

Ce qui change sans préavis

• De nouvelles routes, de nouveaux champs et de nouveaux filtres apparaissent sans annonce. Votre client doit accepter les champs qu’il ne connaît pas.
• Une valeur fausse est corrigée sur place, sous le même nom de champ.
• Un changement de forme donne une nouvelle version, comme /v2/, et l’ancienne version s’en va par ce processus.