Ce guide explique comment Merchant API gère le contrôle des versions, les lancements et le cycle de vie de ses différentes versions.
Schéma de gestion des versions
L'API Merchant utilise une stratégie de gestion des versions au niveau des sous-API. Cela signifie que chaque API Merchant, par exemple Products dans l'API Merchant, aura son propre cycle de vie de version.
Format et présentation du contrôle des versions
Versions stables de sous-API : si une sous-API est dans une version stable, toutes ses méthodes sont dans une version stable. Une version stable de sous-API est représentée par vX (par exemple, v1, v2). Il s'agit de versions majeures prêtes pour la production.
Versions alpha de la sous-API : si une sous-API est en version alpha, toutes ses méthodes sont en version alpha. Une version alpha de sous-API est représentée par vXalpha (par exemple, v1alpha, v2alpha). Ils contiennent des fonctionnalités expérimentales en accès anticipé destinées aux tests et à l'itération rapide. Les versions alpha ne sont pas garanties stables, n'ont pas de durée de vie définie et peuvent être modifiées ou arrêtées avec un préavis de 30 jours.
Modifications apportées à la version
- Incrémentations de version majeure (par exemple, de v1 à v2) : elles signalent des modifications incompatibles avec les versions antérieures et des modifications destructives, qui nécessitent une action de la part du développeur. Seules les modifications destructives des sous-API stables auront un nouveau numéro de version. Par exemple, v1 à v2.
- Modifications mineures : les ajouts ou corrections rétrocompatibles sont présentés comme des modifications de la version majeure existante. Ces modifications seront détaillées dans les notes de version de cette version majeure. Les ajouts non destructifs à une sous-API seront publiés sur la version alpha de la dernière version stable ou directement sur la dernière version stable.
Règle d'abandon définitif
Nous abandonnons régulièrement les anciennes versions de la sous-API Merchant. Nous nous engageons à respecter un délai d'abandon de 12 mois pour les versions majeures stables (vX), à compter de l'annonce officielle de l'abandon.
Par exemple, si nous abandonnons la version 1 de la sous-API Products le 15 janvier 2026, elle sera supprimée au plus tôt le 15 janvier 2027. Après cette date, l'ancienne version de la sous-API ne sera plus disponible.
Version de la sous-API et état du cycle de vie
Le tableau suivant liste les dernières versions de chaque sous-API de l'API Merchant :
| Sous-API | Versions | État |
|---|---|---|
| Comptes | v1 v1alpha |
Actif actif |
| Conversions | v1 | Actif |
| Sources de données | v1 | Actif |
| Stocks | v1 | Actif |
| Résolution des problèmes | v1 | Actif |
| Partenariat pour les flux en magasin | v1 | Actif |
| Notifications | v1 | Actif |
| Suivi de commandes | v1 | Actif |
| Produits | v1 | Actif |
| Product Studio | v1alpha | Actif |
| Promotions | v1 | Actif |
| Quota | v1 | Actif |
| Rapports | v1 | Actif |
| Avis | v1alpha | Actif |
Bonnes pratiques
- Consultez régulièrement les notes de version et les dernières mises à jour pour connaître les nouvelles versions, les mises à jour importantes, les améliorations et les annonces concernant les lancements et les abandons de sous-API.
- Si une sous-API comporte au moins deux versions stables, nous vous suggérons d'utiliser systématiquement la dernière version.
- Concevez votre application de manière à gérer correctement les différentes erreurs de sous-API, y compris les problèmes de réseau, les limitations de débit et les nouveaux codes d'erreur ou messages qui pourraient être introduits avec les nouvelles versions de sous-API.
- N'attendez pas qu'une version de sous-API soit sur le point d'être abandonnée pour commencer à planifier votre mise à niveau. Commencez à évaluer et à tester les nouvelles versions dès qu'elles sont disponibles.
- Pour toute demande de fonctionnalité ou question concernant la feuille de route d'une sous-API, contactez-nous pour nous faire part de vos questions ou de vos commentaires. Pour savoir comment contacter l'équipe Merchant API pour obtenir une assistance technique, consultez Obtenir de l'aide avec Merchant API.