Versionnage

Chaque endpoint répond sur deux chemins :

POST /api/v1/payments/create     versioned, use this
POST /api/payments/create        unversioned, permanently supported

Les deux exécutent aujourd’hui un code identique.

Utilisez le chemin versionné. C’est le seul moyen d’être certain qu’un changement futur ne vous atteindra pas. Une intégration sur le chemin non versionné reçoit ce vers quoi « non versionné » pointe au moment de l’appel : aujourd’hui la v1, et un jour peut-être pas.

Le chemin non versionné est un alias permanent, pas une dépréciation. Il ne sera pas supprimé. Certaines intégrations ne peuvent pas être mises à jour, comme les plugins que les marchands mettent à jour à leur propre rythme, ou jamais, et celles-ci doivent continuer de fonctionner.

Chaque réponse vous indique quelle version l’a servie :

X-API-Version: v1

GET /api/versions liste les versions existantes et indique vers quelle version votre requête a été résolue.

Ce qui constitue un changement cassant

Nous prévenons avant tout changement cassant. Cette promesse n’a de sens que si nous sommes d’accord sur le terme.

Livré sans préavis, dans la version actuelle :

• un nouvel endpoint
• un nouveau champ de requête facultatif
• un nouveau champ de réponse
• une nouvelle valeur d’enum que les clients sont censés tolérer
• une règle de validation assouplie pour accepter davantage d’entrées
• la correction d’une réponse qui n’a jamais correspondu au comportement documenté
• tout changement sans effet visible sur les requêtes ou les réponses

Nécessite une nouvelle version :

• supprimer ou renommer un champ de requête ou de réponse
• modifier le type ou la signification d’un champ
• modifier le code de statut d’un résultat existant
• rendre obligatoire un champ facultatif
• durcir la validation de sorte qu’une entrée auparavant acceptée soit rejetée
• supprimer un endpoint ou modifier son chemin
• modifier ce qui se passe lorsqu’un champ est omis

La règle de fond : si une intégration qui fonctionne aujourd’hui cessait de fonctionner, ou se comportait différemment sans modifier son propre code, le changement est cassant.