Cycle de vie

L’API repose sur un point de terminaison GraphQL unique et évolutif. Cette architecture garantit que les nouvelles capacités et les améliorations de performance sont livrées en continu, sans nécessiter de migration entre des versions de l’API.

Cette page présente les différents niveaux de stabilité de l’API, les garanties de stabilité de l’API stable, les types de changements (majeurs ou non) et la manière dont les dépréciations sont gérées. Pour les fonctionnalités actuellement en préversion, consultez les fonctionnalités expérimentales.

Cycle de vie des fonctionnalités

Chaque fonctionnalité se situe à l’un de ces trois niveaux de stabilité : alpha, bêta ou stable. La plupart des fonctionnalités les parcourent dans l’ordre, et les fonctionnalités stables ne peuvent être retirées que via un processus de dépréciation.

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

API stable

Les fonctionnalités stables constituent le noyau de l’API prêt pour la production. Les changements sont classés en deux catégories : non majeurs et majeurs.

Changements non majeurs

Ajouts rétrocompatibles qui ne perturbent pas les intégrations existantes. Ils sont publiés en continu, sans préavis ni dépréciation.

Les changements non majeurs comprennent :

• L’ajout d’une nouvelle requête, mutation ou souscription.
• L’ajout d’un nouvel argument d’entrée facultatif à une opération existante.
• L’ajout d’un nouvel argument avec une valeur par défaut qui préserve le comportement existant.
• L’ajout d’un nouveau champ à la sortie d’une opération existante.
• Le passage d’un argument d’entrée obligatoire à facultatif.
• L’ajout d’une nouvelle valeur à un type enum existant.

Concevoir en tenant compte des changements non majeurs

Les changements non majeurs peuvent tout de même affecter les clients qui font des hypothèses rigides. Pour garder des intégrations résilientes :

• Évitez la désérialisation stricte des objets, qui échoue lorsque des propriétés supplémentaires apparaissent dans les charges utiles.
• Les types GraphQL enum ne sont pas exhaustifs et s’étendent avec le temps. Implémentez toujours un cas par défaut de repli dans la logique du client.
• Inspectez les valeurs extensions.exception.code des erreurs plutôt que de comparer des chaînes d’erreur lisibles.

Changements majeurs et dépréciations

Un changement majeur peut casser des intégrations actives existantes. Par conséquent, tout changement majeur doit d’abord passer par un processus de dépréciation de 12 mois.

Les changements majeurs comprennent :

• La suppression ou le renommage d’une requête, mutation, souscription, d’un champ ou d’un argument d’entrée existant.
• La suppression ou le renommage de valeurs d’enum.
• Le changement du type de données d’un champ ou d’un argument d’entrée existant.
• L’ajout d’un nouvel argument d’entrée obligatoire.
• Le passage d’un argument d’entrée facultatif à obligatoire.
• La modification de la logique métier ou du comportement d’un champ existant.
• Le passage d’un champ de sortie de non nullable (!) à nullable.
• La modification de la valeur par défaut d’un argument d’entrée ou d’un champ.
• La modification des valeurs par défaut de pagination, des tailles de page maximales ou de l’ordre de tri documenté.

Calendrier de dépréciation

Lorsqu’un changement majeur nécessite de retirer ou de remplacer une capacité stable, il suit un calendrier strict en trois phases :

1. Annonce de la dépréciationLa fonctionnalité est marquée avec la directive @deprecated dans le schéma GraphQL. Le cas échéant, un chemin de migration est fourni. La dépréciation et la date de suppression correspondante sont annoncées simultanément via trois canaux de suivi.
2. Période de préavis active (mois 1 à 12)La fonctionnalité dépréciée reste pleinement opérationnelle. Si un chemin de migration est fourni, les intégrateurs doivent mettre à jour leurs applications et adopter les nouveaux champs pendant cette période de 12 mois.
3. Suppression définitiveÀ la date de suppression, la fonctionnalité est définitivement retirée. Toute requête ultérieure utilisant cette fonctionnalité échouera à la validation du schéma avec une erreur GraphQL.

Suivi des dépréciations

Identifiez et suivez les retraits à venir via trois canaux :

• Inspectez les directives @deprecated(reason: "...") dans vos outils de schéma.
• Consultez les dates de fin de support et les guides de migration dans la section héritée de l’API ou sur le portail des dépréciations.
• Surveillez les avertissements DEPRECATED_FEATURE renvoyés directement dans les réponses de l’API.

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}