Dépréciation des API Shopify : l'édition 2022-01

Bienvenue dans une nouvelle édition de la dépréciation des API chez Shopify, où nous nous intéressons aux changements non rétrocompatibles qui entreront en vigueur pour toutes les versions prises en charge. Dans cette édition, nous reviendrons sur les changements non rétrocompatibles introduits dans notre version 2021-04, qui deviendra la plus ancienne version prise en charge au 1er janvier 2022. Nous aborderons notamment certains points essentiels pour les développeurs d'applications privées. Voyons tout cela en détail.

Un rapide rappel sur le versioning

Avant de nous lancer dans les changements à venir, voici un récapitulatif du fonctionnement du versioning de l'API chez Shopify.

• Nous sortons une version tous les trimestres. Ces sorties ont généralement lieu le ou vers le 1er janvier, le 1er avril, le 1er juillet et le 1er octobre. Les versions sont nommées selon un format année-mois (par exemple 2022-01), ce qui permet de toujours identifier facilement le moment où la version est devenue stable, ainsi que de comparer les calendriers de plusieurs versions.
• Les applications effectuent des requêtes vers une version spécifique de l'API en la spécifiant dans l'URL de la requête. Bien que les API de Shopify évoluent en permanence, les applications peuvent être construites sur une version stable afin de garantir que le contrat de l'API reste constant. Gardez à l'esprit que cela signifie que toutes les fonctionnalités publiées après la version ciblée ne seront pas accessibles tant que vous n'aurez pas mis à jour l'URL de votre requête.
• Nous mettons continuellement de nouvelles fonctionnalités à disposition des marchands. Afin d'offrir ces fonctionnalités sans affecter les dernières API stables, nous utilisons des versions candidates. La version candidate est simplement la prochaine version de l'API, et peut être ciblée pour les requêtes en utilisant le même format année-mois. Dans la version candidate, vous trouverez le dernier ensemble de fonctionnalités qui vient d'être publié. Cependant, comme elle est en constante évolution, vous devez éviter d'utiliser la version candidate pour les appels d’API quotidiens de votre application. Pour bénéficier à la fois de la stabilité et de l'accès aux dernières fonctionnalités, nous vous recommandons de conserver les requêtes quotidiennes de votre application dans une version stable, et de ne déplacer vers la version candidate que les appels spécifiques qui concernent des fonctionnalités récemment publiées.
• Les applications qui ne demandent pas une version spécifique obtiennent la version la plus ancienne prise en charge. Cela permet aux applications existantes de continuer à fonctionner lorsque nous lançons le versioning, sans avoir à faire de mise à jour avec les nouvelles URL. Ce concept s'applique également aux applications faisant appel à des versions qui ne sont plus prises en charge. Bien que chaque application bénéficie de ce mécanisme qui empêche toutes les requêtes d’afficher des erreurs après un changement de version, nous recommandons de cibler intentionnellement les versions récentes.
• Les versions sont prises en charge pendant un an. La suppression de la prise en charge des versions nous permet d'apporter les modifications nécessaires pour servir au mieux nos marchands et la plateforme Shopify sur le long terme. Si les versions sont prises en charge pendant un an, cela signifie cependant que les applications n'ont en fait que neuf mois pour adopter ces nouveaux changements et profiter des nouvelles fonctionnalités avant que l'ancien comportement ne soit plus disponible.

Avec ce récapitulatif en tête, passons en revue les informations clés dont vous aurez besoin pour être prêt pour le 1er janvier 2022.

Ce qui va se passer le 1er janvier

Le 1er janvier 2022, les changements suivants entreront en vigueur sur nos API pour les applications publiques comme pour les applications privées :

• La version 2022-01 deviendra stable et prête à être utilisée.
• La version 2021-01 ne sera plus prise en charge.
• Les requêtes obsolètes suite aux changements dans 2021-04 entraîneront le signalement de votre application. Pour minimiser l'impact sur les marchands, Shopify supprimera les applications signalées de l'App Store de Shopify et bloquera les nouvelles installations. Il est également possible que nous informions les marchands du fait que vos applications ne sont plus prises en charge.

Peu de temps après, à la date que nous aurons choisie :

• Les requêtes ne comportant pas de version API spécifiée seront renvoyées vers la version 2021-04.
• Les requêtes pour la version 2021-01 ne recevront plus cette version. Ces requêtes seront renvoyées vers la version 2021-04.
• Les webhooks fixés à 2021-01 seront renvoyés de la même manière.

Attention, la version 2021-04 de l'API, qui deviendra la version par défaut, comprend des changements non rétrocompatibles de l'API. Si votre application émet des requêtes qui ne sont pas prises en charge par la version 2021-01, vous devez faire en sorte de migrer ces requêtes avant le 1er janvier 2022. Si vous ne le faites pas, les requêtes échoueront et l'application affichera des erreurs.

Changements non rétrocompatibles à venir

Vous trouverez ci-dessous les changements non rétrocompatibles introduits en 2021-04, qui deviendra la plus ancienne version supportée par Shopify au 1er janvier 2022.

Champ nextAction pour les applications de paiement

À partir de la version 2021-04 de l’API, les applications de paiement qui utilisent le champ redirectUrl dans l’objet PaymentSession devront être mises à jour afin d’utiliser le champ nextAction (action suivante).

Jusqu’à présent, les applications qui traitaient un paiement devaient utiliser le champ redirectUrl pour rediriger le client vers le site une fois qu'il avait effectué son paiement en dehors du site. Ce champ redirectUrl était spécifique aux paiements hors site. Pour prendre en charge d’autres modes de paiement, et d'autres actions qui pourraient être nécessaires en fonction du type de paiement, nous avons ajouté les champs suivants pour PaymentSessionNextAction :

• action : l’action que l'application de paiement doit effectuer. REDIRECT indique que le client doit être redirigé une fois le paiement effectué et nil indique qu’aucune autre action n’est nécessaire pour terminer le processus de paiement.
• context : toutes les données nécessaires pour exécuter l'action. Actuellement, la seule valeur possible est PaymentSessionActionsRedirect.

Préparez-vous pour le 1er janvier 2022

Les ressources suivantes peuvent vous aider à vous informer des changements apportés à la plateforme Shopify :

• Rapport sur la santé des API : ce rapport de santé par application est disponible dans le tableau de bord des partenaires et vous présente les modifications exactes de l'API qui vous concernent.
• E-mail : assurez-vous que l’adresse e-mail de votre développeur est à jour afin que nous puissions vous informer des changements à venir.
• En-têtes de dépréciation : dans votre application, l'en-tête HTTP X-Shopify-API-Deprecated-Reason est ajouté aux requêtes dépréciées qui ne seront plus prises en charge d’ici neuf mois.
• Journal des changements pour les développeurs : restez au courant des dernières modifications apportées aux API de Shopify et aux autres produits destinés aux développeurs.
• Point de terminaison pour les appels d'API dépréciés : les applications privées peuvent accéder aux informations relatives à la santé de leurs API via ce point de terminaison.

Consultez les notes de la version 2022-01 pour connaître l’ensemble des nouvelles fonctionnalités ou votre tableau de bord des partenaires pour savoir quels changements peuvent vous concerner.

---

Publié par Maud Leuenberger. Maud est la rédactrice en chef du blog français de Shopify.

Texte original par Nevin Tan. Traduction par Solenn Marchand.