Versionnage

Comment ça marche

Le chemin porte la version majeure, comme dans /v1/api/properties. Une deuxième version majeure signifierait une refonte complète, cohabiterait avec la v1 plutôt que de la remplacer, et n'est pas quelque chose que nous comptons faire à la légère.

L'évolution quotidienne passe par une révision datée. Épinglez-la avec un en-tête et votre intégration conserve le comportement pour lequel elle a été écrite :

Skautik-Version: 2026-08-01

Omettez l'en-tête et la révision par défaut de votre organisation s'applique, à savoir celle en vigueur lors de la création de votre première clé. Elle n'est pas avancée en silence : une intégration ne peut donc pas casser parce que nous avons livré quelque chose. Chaque réponse répète la révision qui l'a servie.

Ce que nous pouvons changer sans nouvelle révision

Ces changements sont additifs, et un client qui suit une seule règle les tolère tous : ignorez les champs que vous ne reconnaissez pas. Un analyseur qui rejette les propriétés inconnues cassera à notre prochaine livraison, et c'est évitable.

• Un nouvel endpoint.
• Un nouveau paramètre de requête facultatif.
• Un nouveau champ sur une réponse existante.
• Une nouvelle valeur dans une énumération que vous ne faites que lire.
• Un nouveau type d'événement de webhook.
• L'assouplissement d'une règle de validation qui rejetait quelque chose.

Ce qui exige une nouvelle révision

Tout ce qui pourrait casser un client correct reçoit une nouvelle révision datée. Votre révision épinglée continue de se comporter comme documenté.

• Supprimer ou renommer un endpoint, un paramètre ou un champ de réponse.
• Changer le type ou l'unité d'un champ existant.
• Rendre obligatoire un paramètre facultatif, ou durcir la validation.
• Changer la valeur par défaut d'un paramètre.
• Changer le sens d'une valeur d'énumération existante.
• Supprimer un type d'événement de webhook.

Dépréciation

Quand quelque chose est en voie de disparition, cela continue de fonctionner et commence à s'annoncer. Les endpoints dépréciés renvoient :

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

• Au moins 12 mois entre un avis de dépréciation et la suppression, pour tout ce qui figure dans une révision publiée.
• Nous écrivons au contact technique de l'organisation au début d'une dépréciation, puis de nouveau à l'approche de l'échéance, plutôt que de compter sur votre lecture d'un journal des modifications.
• Placez une alerte sur l'en-tête Deprecation dans votre propre supervision. C'est l'avertissement le plus précoce possible et le surveiller ne coûte rien.

Écrire un client durable

• Épinglez la révision explicitement plutôt que de vous fier au défaut de votre compte.
• Ignorez les champs et les valeurs d'énumération inconnus au lieu d'échouer dessus.
• Traitez les identifiants comme des chaînes opaques ; n'analysez jamais un préfixe pour lui donner un sens.
• Ne dépendez pas de l'ordre des champs, de l'absence d'un champ, ni d'un décompte que l'API ne promet pas.
• Branchez sur les codes d'erreur, pas sur la prose des erreurs.