Dépréciation des API Shopify : l’édition 2021-01

Bienvenue dans la dernière édition 2020 de la dépréciation des API chez Shopify. Intéresserons-nous aux prochaines modifications qui entreront en vigueur pour toutes les versions prises en charge et revenons sur les changements qui ont été apportés à notre version d'avril 2020, qui deviendra la plus ancienne version de l'API de Shopify prise en charge à la date du 1er janvier 2021. Voici ce qu'il faut retenir. 

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 2 juillet et le 1er octobre. Les versions sont nommées selon un format année-mois (par exemple 2021-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 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 l’utilisation quotidienne de l'API 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 2021.

Lecture conseillée : comment développer une application Shopify en une semaine.

Ce qui va se passer le 1er janvier

Le 1er janvier 2021, les changements suivants entreront en vigueur sur nos API:

• La version 2021-01 deviendra stable et prête à être utilisée.
• La version 2020-01 ne sera plus supportée.
• Les demandes obsolètes suite aux changements dans 2020-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 :

• Les requêtes ne comportant pas de version API spécifiée seront renvoyées vers la version 2020-04.
• Les requêtes pour la version 2019-10 ne seront pas prises en compte sous cette version. Ces requêtes seront renvoyées vers la version 2020-04.
• Les webhooks fixés à 2019-10 seront renvoyés de la même manière.

Plus important encore, la version 2020-04 de l'API, qui deviendra la version par défaut, comprend des « changements cassants » de l'API. Si votre application émet des requêtes qui ne sont pas supportées par la version 2020-04, vous devez faire en sorte de migrer ces requêtes avant le 1er janvier 2021. Si vous ne le faites pas, les requêtes échoueront et l'application affichera des erreurs.

Changements à venir

Vous trouverez ci-dessous les changements introduits en 2020-04, qui deviendra alors la plus ancienne version supportée par Shopify au 1er janvier.

1. Nouvelles validations sur la tarification

Pour les variantes, le champ compare_at doit désormais toujours être plus grand que le champ price. L'ajout de cette validation permettra aux applications de faire confiance au lien entre ces valeurs, ce qui leur permettra de faire apparaître le compare_at_price dans de nouvelles zones (par exemple sur un reçu) sans se soucier des valeurs impaires.

Ce qu’il faut retenir : lorsque vous fixez les prix, assurez-vous que le champ compare_at est toujours plus grand que le champ price. Si vous ne le faites pas, vous obtiendrez une erreur 422.

2. Suppression des mutations liées aux réductions de prix

Nous avons publié deux mutations construites autour de la modification en bloc des réductions de prix dans 2020-01, productBulkAddPriceReductions et productBulkRemovePriceReductions.

Après examen, nous avons estimé qu'elles n'étaient pas tout à fait prêtes pour une utilisation à grande échelle, et nous avons donc décidé de les supprimer du schéma.

Ce qu’il faut retenir : les mutations productBulkAddPriceReductions et productBulkRemovePriceReductions ont été supprimées.

3. Nouveaux codes d'erreur pour les objets media

Nous avons ajouté des codes d'erreur supplémentaires pour les objets media, permettant un diagnostic plus spécifique. Nous considérons ces types de modifications comme des ruptures, car l'ajout d'une valeur à une enum signifie que votre application peut commencer à voir de nouvelles valeurs qu’elle ne voyait pas auparavant.

Ce qu’il faut retenir : lorsque vous travaillez avec des objets media, mettez à jour l'analyse des erreurs pour gérer de nouvelles valeurs.

4. Nouveaux codes d'erreur pour les clients sur l'API Storefront

Comme ci-dessus nous avons ajouté des codes d'erreur supplémentaires pour les clients sur l'API Storefront.

Ce qu’il faut retenir : lorsque vous travaillez pour vos clients, mettez à jour l'analyse des erreurs pour gérer de nouvelles valeurs.

Préparez-vous pour le 1er janvier 2020

Les ressources suivantes peuvent vous aider à vous tenir informé 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.
• Email : Assurez-vous que l’email de votre développeur est à jour afin que nous puissions vous informer des changements en cours.
• En-têtes dépréciées : dans votre application, l'en-tête X-Shopify-API-Deprecated-Reason est ajoutée aux requêtes dépréciées qui ne seront plus prises en charge d’ici neuf mois.
• Developer changelog : restez au courant des dernières modifications apportées aux API de Shopify et aux autres produits destinés aux développeurs.
• Endpoint pour les appels d'API dépréciés : les applications privées n'ayant pas accès au rapport de santé API, nous avons mis en place un nouveau endpoint pour demander ces données.

En janvier prochain, assurez-vous que vos applications soient prêtes pour la nouvelle année grâce à ces nouvelles validations et aux améliorations apportées au traitement des erreurs en migrant vers 2020-04.

Consultez les notes de la version 2021-01 pour connaître l'ensemble des nouvelles fonctionnalités et votre tableau de bord partenaire pour savoir quels changements peuvent vous concerner.