Cycle de vie

L’API est construite autour d’un unique endpoint GraphQL é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 d’API.

Cette page décrit les différents niveaux de stabilité de l’API, les garanties de stabilité de l’API stable, les types de changements (incompatibles ou compatibles) et la gestion des obsolescences. 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 des 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 d’obsolescence.

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

API stable

Les fonctionnalités stables constituent le cœur de l’API, prêt pour la production. Les changements sont classés en deux catégories : compatibles et incompatibles.

Changements compatibles

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

Les changements compatibles incluent :

• L’ajout d’une nouvelle query, mutation ou subscription.
• L’ajout d’un nouvel argument d’entrée optionnel à 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 à optionnel.
• L’ajout d’une nouvelle valeur à un type enum existant.

Concevoir pour les changements compatibles

Les changements compatibles 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 enum GraphQL ne sont pas exhaustifs et s’étendent au fil du 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 par un humain.

Changements incompatibles et obsolescences

Un changement incompatible pourrait casser des intégrations actives existantes. Par conséquent, tout changement incompatible doit d’abord passer par un processus d’obsolescence de 12 mois.

Les changements incompatibles incluent :

• La suppression ou le renommage d’une query, mutation, subscription, d’un champ ou d’un argument d’entrée existant.
• La suppression ou le renommage de valeurs d’enum.
• La modification 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 optionnel à 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 d’obsolescence

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

1. Annonce de l’obsolescenceLa fonctionnalité est marquée avec la directive @deprecated dans le schéma GraphQL. Le cas échéant, un chemin de migration est fourni. L’obsolescence et la date de suppression correspondante sont annoncées simultanément sur trois canaux de suivi.
2. Période de préavis active (mois 1 à 12)La fonctionnalité obsolète 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 supprimée. Toute requête ultérieure utilisant la fonctionnalité échouera à la validation du schéma avec une erreur GraphQL.

Suivi des obsolescences

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 et les guides de migration dans la section héritée de l’API ou sur le portail des obsolescences.
• 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."      }    ]  }}