/api/external/v1. Le numéro de la documentation (info.version, par exemple 1.0.0) suit le versionnage sémantique ; chaque changement est daté dans l’Historique des versions.
Écrire un client qui tolère les évolutions
- Ignorez les champs de réponse que vous ne connaissez pas. La spécification décrit les champs actuels ; elle n’interdit pas d’en recevoir d’autres.
- Tolérez une valeur d’énumération inconnue en sortie (statut, type d’événement, motif…) : prévoyez toujours un cas par défaut.
- Le catalogue des codes d’erreur est extensible : traitez un
codeinconnu selon son statut HTTP. - Dans vos requêtes, n’envoyez que les champs documentés : un champ inconnu est refusé (
400).
Évolutions sans préavis
Elles ne cassent aucun client qui suit les règles ci-dessus :- nouvelle opération ;
- nouveau champ de réponse ;
- nouveau paramètre ou nouveau champ de requête facultatif ;
- nouveau code d’erreur.
Évolutions annoncées 30 jours avant
Une nouvelle valeur d’une énumération en sortie, y compris un nouveau type d’événement, est annoncée dans l’historique au moins 30 jours avant d’apparaître.Correctifs de contrat
Un correctif de sécurité, d’intégrité des données ou de bug, ou l’alignement de la documentation sur le comportement réel, s’applique à lav1 sans préavis. Il est daté dans l’historique, avec la marche à suivre.
Évolutions cassantes
Hors correctif de contrat, elles ne paraissent que dans une nouvelle version majeure (v2), servie en parallèle. La v1 reste disponible 6 mois après l’annonce, et ses réponses portent alors les en-têtes Deprecation et Sunset.