Versionnage de l'API

L'API publique utilise des versions datées, le même schéma que Shopify, afin que la version sur laquelle vous développez ne change pas sous vos pieds. Les versions datées constituent la frontière grossière des changements incompatibles ; à l'intérieur d'une version, le schéma continue d'évoluer par ajouts uniquement.

Noms des versions

Une version porte le nom YYYY-MM, où le mois correspond à un début de trimestre : 2026-01, 2026-04, 2026-07, 2026-10. Une nouvelle version datée n'est publiée que lorsqu'il y a un changement incompatible — les trimestres sans changement incompatible sont sautés, si bien que les versions sont relativement rares.

Il existe aussi une version unstable qui suit la pointe du développement et permet de prévisualiser les changements avant une publication stable. Ne bâtissez pas d'intégrations de production dessus.

Choisir une version

Deux moyens, par ordre de priorité :

1. Chemin d'URL (recommandé) : placez la version dans le point de terminaison — …/backend/<subdomain>/api/2026-07/graphql. C'est explicite, favorable au cache et facile à copier-coller.
2. En-tête de requête : envoyez X-Api-Version: 2026-07 au point de terminaison simple …/backend/<subdomain>/graphql.

Si vous omettez la version — ou si vous en indiquez une inconnue ou dont la date de retrait est passée — la requête est servie par la plus ancienne version encore prise en charge, jamais la plus récente. Vous n'êtes jamais basculé en silence sur un changement incompatible. Épinglez explicitement une version pour toute intégration que vous comptez maintenir.

Chaque réponse indique la version qui l'a servie dans un en-tête X-Api-Version : vous savez donc toujours quel contrat a répondu — et vous détectez toute dérive si vous vous êtes reposé sur le repli automatique.

Période de prise en charge

Chaque version stable est prise en charge pendant au moins 12 mois, avec au moins 9 mois de chevauchement avec la suivante. En pratique, deux à trois versions sont actives à tout moment, ce qui laisse une fenêtre confortable pour migrer. La date de retrait d'une version est publiée le jour de sa sortie.

Ce qui compte comme changement incompatible

À l'intérieur d'une même version, nous pouvons effectuer des changements par ajout, et votre client doit les tolérer :

• ajouter un nouveau type, une requête ou une mutation ;
• ajouter un argument facultatif à un champ existant ;
• ajouter un champ à un type objet ;
• ajouter une valeur à une énumération (ne supposez donc jamais qu'une énumération est fermée).

Une nouvelle version datée est réservée aux changements véritablement incompatibles : supprimer ou renommer un champ ou un type, renforcer la nullabilité, ou modifier le sens d'un argument ou d'une valeur par défaut. Ceux-ci n'arrivent jamais au sein d'une version existante — la version que vous avez épinglée conserve son comportement jusqu'à sa date de retrait.

Dépréciations

Les dépréciations sont signalées de deux manières, afin que vous en soyez informé avant que quoi que ce soit ne casse :

• Dans le schéma. Un champ en cours de retrait est marqué @deprecated avec une raison qui nomme son remplaçant. L'introspection et le GraphQL Playground l'exposent automatiquement à tout client.
• Dans la réponse. Lorsqu'une requête résout effectivement un champ déprécié, la réponse porte un en-tête X-Api-Deprecated-Reason (et une entrée extensions.deprecations correspondante) nommant les dépréciations précises qu'elle a touchées — une dépréciation apparaît donc dans vos journaux dès que vous en rencontrez une, sans que vous ayez à la chercher.

Un champ déprécié est conservé pendant une période minimale publiée avant d'être supprimé dans une version datée ultérieure.