Versionnage de l'API Stripe : fonctionnement et à copier

Le versionnage de l’API Stripe fonctionne par date. Chaque compte est épinglé sur une version d’API nommée d’après une date de publication, et n’importe quelle requête peut remplacer cet épinglage avec un en-tête Stripe-Version. Au moment de la rédaction (octobre 2026), la version actuelle dans la documentation de Stripe est 2026-09-30.endive, et le même schéma est à la portée d’une API bien plus petite, en un week-end.

Chaque fait sur Stripe ci-dessous vient des pages de Stripe elles-mêmes, liées à l’endroit où il est utilisé.

Comment fonctionne le versionnage de l’API Stripe ?

Stripe donne à chaque compte une version d’API par défaut, et toute requête qui ne nomme pas de version l’utilise. Les appelants choisissent quand changer, en modifiant la valeur par défaut ou en indiquant une version sur chaque requête.

L’article d’ingénierie de Stripe explique que le compte est épinglé dès sa première requête à l’API : il est “automatically pinned to the most recent version available”, et ensuite chaque appel se voit attribuer cette version de manière implicite.

La version est une chaîne de date. Depuis la release 2024-09-30.acacia, elle porte aussi un nom, comme dans 2026-09-30.endive. La date ordonne les versions, et le nom indique à quelle famille de release majeure appartient une version.

Comment choisir une version par requête ?

Envoyez l’en-tête Stripe-Version avec la requête, ou définissez la version dans le SDK. Le guide de mise à niveau de Stripe montre la forme avec l’en-tête, et le même appel fonctionne en production comme en test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Le guide de Stripe précise que lorsque vous définissez la version globalement ou par requête dans un SDK, les objets de réponse reviennent dans cette version.

Stripe déconseille aussi de s’appuyer sur la valeur par défaut du compte. Selon ses termes, indiquez la version pour chaque requête, avec l’en-tête ou un SDK épinglé, afin que votre code décide de la version et non un réglage du tableau de bord.

Les SDK s’épinglent différemment selon le langage. La documentation dit que les versions récentes des bibliothèques à typage dynamique utilisent la version d’API qui était la plus récente à la sortie de cette version du SDK, et que les bibliothèques fortement typées (Java, Go et .NET) y sont fixées. Installer une version de bibliothèque revient, en pratique, à choisir une version d’API.

Que deviennent les webhooks quand la version change ?

Un événement webhook est rendu dans la version d’API rattachée à son endpoint, et non dans celle que le code de votre serveur utilise. La documentation de Stripe indique que les événements utilisent la version définie à la création de l’endpoint, et sinon la valeur par défaut du compte. Changer la version de votre SDK ne change pas ce que reçoit votre gestionnaire de webhooks.

Votre chemin de requêtes et votre chemin d’événements peuvent donc reposer sur deux versions différentes. Pour les destinations d’événements, vous ne définissez snapshot_api_version qu’à la création de la destination ; une autre version signifie donc une nouvelle destination.

Le chemin de mise à niveau de Stripe pour cela est une exécution en parallèle. Créez un nouvel endpoint à la version cible, envoyez les mêmes événements aux deux, apprenez au gestionnaire à traiter l’un et à ignorer l’autre, puis basculez et désactivez l’ancien endpoint. Comme chaque événement arrive deux fois pendant le chevauchement, le gestionnaire doit être idempotent. C’est un bon schéma à copier pour toute API qui émet des événements, et un changelog de webhooks est l’endroit où annoncer les changements de charge utile qui le rendent nécessaire.

Que sont les releases mensuelles et majeures ?

Depuis la release 2024-09-30.acacia, Stripe publie une nouvelle version d’API chaque mois sans changement cassant, et émet une nouvelle release majeure deux fois par an, qui démarre avec une version contenant des changements cassants. Sa page de versionnage indique que vous pouvez passer à n’importe quelle release mensuelle sans modifier votre code, alors qu’une release majeure peut exiger des changements.

Les releases majeures portent des noms. La page de versionnage donne Basil en exemple, et l’annonce du processus par Stripe dit que les noms viennent de plantes, en commençant par Acacia, et que les releases mensuelles gardent le nom de la release majeure qui les précède pour signaler qu’on peut les adopter sans risque. Le changelog de Stripe liste les noms en usage, et au moment de la rédaction l’entrée la plus récente est 2026-09-30.endive.

La date répond donc à “quelle fraîcheur”, et le nom à “est-ce une frontière cassante”. L’annonce de Stripe garde aussi une marge pour les exceptions : elle se réserve le droit de publier un changement cassant hors cycle lorsqu’une intégration serait gravement touchée sans lui. L’annonce est sur Stripe’s new API release process.

Quelle est la dernière version de l’API Stripe ?

Au moment de la rédaction (octobre 2026), la page de versionnage de Stripe indique que la version actuelle est 2026-09-30.endive, et son changelog liste la même version comme la plus récente. Stripe publie une nouvelle version chaque mois, donc toute chaîne imprimée dans un article vieillit vite. Lisez le changelog en direct avant d’épingler quoi que ce soit, et épinglez la version contre laquelle vous avez testé.

Comment Stripe maintient-il les anciennes versions ?

Stripe garde les anciennes versions en vie en écrivant chaque changement cassant sous forme de module de changement de version autonome et en appliquant les modules à rebours depuis la forme la plus récente des données. Son article d’ingénierie sur le versionnage d’API décrit le mécanisme.

Chaque module déclare ce qu’il change, documente le changement et inclut une fonction de transformation. L’article donne l’exemple d’un champ qui passe d’une chaîne à un hash. Pour construire une réponse, le système détermine la version cible, puis remonte le temps en appliquant chaque module rencontré en chemin jusqu’à atteindre cette version.

Deux effets de bord découlent de cette conception, et l’article nomme les deux. Comme les modules déclarent les champs et ressources qu’ils touchent, Stripe peut générer son changelog d’API à partir d’eux au déploiement. Et comme la version du compte est connue, la documentation peut s’y adapter et avertir des changements rétro-incompatibles depuis cette version.

Que coûte-t-il, et que doit copier une API plus petite ?

Le versionnage coûte de l’attention d’ingénierie, et Stripe le dit. L’article reconnaît une charge de maintenance et pose comme objectif que moins il faut penser aux anciens comportements en écrivant du nouveau code, mieux c’est. Il décrit aussi des revues d’API légères avant la sortie, pour éviter d’avoir besoin d’un changement de version.

Une petite API n’a pas les moyens d’avoir une chaîne de modules pour chaque ancienne version, et n’en a pas besoin. Copiez les éléments qui portent la valeur :

1. Des versions datées. Une date n’exige aucun jugement sur ce qui compte comme “majeur”, et les appelants peuvent la lire. L’article sur les bonnes pratiques de versionnage la compare aux schémas par URL et par en-tête.
2. Une version par défaut épinglée. Fixez le compte ou la clé sur la version au premier usage, pour que l’API ne bouge jamais sous une intégration qui fonctionne.
3. Un remplacement par requête. Un en-tête qui permet à un appelant de tester une nouvelle version sur un seul appel, en production, avant de s’engager.
4. Une version sur l’endpoint de webhook. Les charges utiles d’événements sont l’endroit où les appelants sont le plus surpris.
5. Une entrée de changelog par version. Qu’elle nomme la version, la date, les personnes concernées et ce qu’il faut faire. Ce qui compte comme cassant est le test de ce qui a sa place dans une nouvelle version, et l’article sur le changelog d’API couvre l’entrée elle-même.

Sautez la chaîne de modules jusqu’à ce que le nombre de versions prises en charge l’impose. Deux ou trois versions actives se gèrent avec quelques branches et une date d’arrêt, que mettre fin à une version d’API détaille.

Si vous publiez un changelog daté, l’historique des versions ne vaut que ce que valent ses entrées. Dans Changeloop, une entrée brouillon est créée à partir de chaque pull request fusionnée et retenue jusqu’à l’approbation d’un humain avant d’être publiée sur la page de changelog et le flux. C’est là qu’on écrit l’entrée de chaque version, et l’unique validation humaine est la relecture qui dit ce qu’un appelant doit faire.

FAQ

Quelle est la dernière version de l’API Stripe ? Au moment de la rédaction (octobre 2026), la page de versionnage de Stripe indique que la version actuelle est 2026-09-30.endive. Stripe publie une nouvelle version chaque mois ; consultez donc son changelog avant d’épingler, et écrivez la version dans votre code au lieu de vous fier à la valeur par défaut du compte.

Comment définir la version de l’API Stripe sur une requête ? Envoyez l’en-tête Stripe-Version, par exemple Stripe-Version: 2026-09-30.endive, ou définissez la version dans votre SDK côté serveur, globalement ou par requête. Sans l’un ni l’autre, une requête utilise la version par défaut de votre compte, que vous définissez dans Workbench.

Les webhooks utilisent-ils la même version de l’API Stripe que mes requêtes ? Pas forcément. Les événements webhook utilisent la version définie à la création de l’endpoint, et la valeur par défaut du compte si aucune n’a été définie. Mettre à jour votre SDK ne change pas la charge utile que reçoit votre gestionnaire de webhooks ; mettez donc les endpoints à niveau séparément et testez-les en parallèle.

Le versionnage par date à la Stripe convient-il à une petite API ? Des versions datées, une version par défaut épinglée, un en-tête par requête et une entrée de changelog par version coûtent peu et valent d’être copiés. La chaîne interne de modules de changement de version, non, tant que vous n’avez pas à prendre en charge de nombreuses anciennes versions à la fois. Commencez avec deux versions actives et une date d’arrêt pour la plus ancienne.

Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.

À voir sur changeloop : Documentation développeurs