Bienvenue dans une nouvelle édition de la dépréciation des API chez Shopify, où nous nous intéressons aux modifications critiques qui entreront en vigueur pour toutes les versions prises en charge. Dans cette édition, nous reviendrons sur les changements qui ont été introduits dans notre version d’octobre 2020, qui deviendra la plus ancienne version prise en charge au 1er juillet 2021. 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 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 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 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 juillet 2021.
Ce qui va se passer le 1er juillet
Le 1er juillet 2021, les changements suivants entreront en vigueur sur nos API pour les applications publiques comme pour les applications privées :
- La version 2021-07 deviendra stable et prête à être utilisée.
- La version 2020-07 ne sera plus prise en charge.
- Les demandes obsolètes suite aux changements dans 2020-10 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 2020-10.
- Les requêtes pour la version 2020-07 ne seront pas prises en compte sous cette version. Ces requêtes seront renvoyées vers la version 2020-10.
- Les webhooks fixés à 2020-07 seront renvoyés de la même manière.
Attention, la version 2020-10 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 prises en charge par la version 2020-10, vous devez faire en sorte de migrer ces requêtes avant le 1er juillet 2021. Si vous ne le faites pas, les requêtes échoueront et l’application affichera des erreurs.
Voyons maintenant en détail les changements introduits dans la version 2020-10.
Changements à venir
Les changements suivants seront introduits le 1er juillet 2021.
Données du champ Tax
Les champs Tax (Taxes) des ressources Country (Pays) et Province ont été abandonnés. Vous ne pourrez plus les créer ni les modifier.
En-tête include-risk-analysis
L’en-tête include-risk-analysis
qui fournissait les objets risks
et risk analysis
de la charge utile Order (Commande) a été supprimé. Notez que l’existence de cet en-tête n’était pas documentée.
Paramètre de champ type
Le paramètre de champ type
sur CodeDiscountQuery
a été abandonné. Le paramètre de champ discount_type
doit être utilisé à la place.
Champs abandonnés dans les objets Refund et RefundLineItem
Deux champs ont été abandonnés, chacun dans un objet différent de l’API administrateur GraphQL :
- Le champ
restocked
de l’objet Refund a été abandonné. Le champRefundLineItem.restockType
doit être utilisé à la place. - Le champ
refundType
de l’objet RefundLineItem a été abandonné. Le champRefundLineItem.restockType
doit être utilisé à la place.
Préparez-vous pour le 1er juillet 2021
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.
- 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 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 2021-07 pour connaître l’ensemble des nouvelles fonctionnalités, votre tableau de bord des partenaires pour savoir quels changements peuvent vous concerner.
Rejoignez le programme des partenaires de Shopify
Inscrivez-vous gratuitement au programme partenaires de Shopify. Accédez à des outils et ressources pour aider les marchands Shopify à développer leur activité et faites partie d’un écosystème riche en opportunités.
Devenir partenaire ShopifyPublié 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.