Stabilité de l'API, versionnement et obsolescence
Avant de construire durablement sur la RealityConnect API, comprenez quelles parties de la surface sont stables, comment les opérations expérimentales sont marquées, et à quoi vous attendre d’une mise à jour à l’autre.
Opérations expérimentales
Section intitulée « Opérations expérimentales »Certaines opérations de la référence API portent un marqueur de stabilité expérimental. Repérez x-scalar-stability: experimental sur une opération dans le document OpenAPI (visible comme badge de stabilité dans la référence API rendue) pour les identifier. Cette information est tenue à jour automatiquement avec l’API, mieux vaut donc s’y référer plutôt que de se fier à une liste figée ici.
Les opérations expérimentales sont réelles et utilisables (ni désactivées ni réservées à un aperçu), mais leurs chemins, paramètres, payloads, réponses ou disponibilité peuvent changer sans les mêmes garanties de stabilité que le reste de l’API. Voir Getting Started : Points de terminaison expérimentaux pour savoir comment les utiliser.
Lorsqu’une opération expérimentale devient stable, cela est signalé dans les notes de version.
Changements cassants et non cassants
Section intitulée « Changements cassants et non cassants »| Changement | Cassant ? | Pourquoi |
|---|---|---|
| Nouveau paramètre de requête optionnel | Non | Les requêtes existantes continuent de fonctionner sans changement |
| Nouveau champ de réponse | Non | Les clients existants qui lisent des champs connus ne sont pas affectés ; parsez les réponses de manière tolérante et ignorez les champs inconnus |
| Nouvelle valeur d’énumération ajoutée à un champ existant | Non | Traitez les champs d’énumération comme des ensembles ouverts et gérez les valeurs inconnues avec souplesse, plutôt que de faire correspondre exhaustivement chaque valeur connue |
| Champ existant supprimé ou renommé | Oui | Casse tout client lisant ce champ |
| Type ou signification d’un champ existant modifié | Oui | Casse tout client s’appuyant sur la forme précédente |
| Paramètre requis ajouté à une opération existante | Oui | Casse les requêtes existantes qui ne l’envoient pas |
| Chemin ou méthode HTTP d’un point de terminaison modifié | Oui | Casse purement et simplement les requêtes existantes |
| Le contrat d’une opération expérimentale change | Non (voulu) | Les opérations expérimentales sont explicitement exemptées du contrat de stabilité ; voir ci-dessus |
Politique d’obsolescence
Section intitulée « Politique d’obsolescence »Avant d’être retirée, une opération stable est déclarée obsolète avec une date de fin de vie (sunset). La référence API marque l’opération comme obsolète, et sa définition OpenAPI porte deprecated: true et la date de fin de vie dans x-sunset (YYYY-MM-DD).
- Une opération stable obsolète continue de fonctionner jusqu’à sa date de fin de vie, et peut être retirée à partir de cette date.
- Il n’existe pas de délai de préavis minimal fixe : la date de fin de vie de chaque obsolescence constitue son préavis.
- Un paramètre de requête obsolète avec une date de fin de vie suit la même règle.
- Certains paramètres de requête sont renommés avec un alias rétrocompatible : l’ancien nom continue de fonctionner aux côtés du nouveau.
- Les opérations expérimentales en sont exemptées : elles peuvent être déclarées obsolètes sans date de fin de vie, et modifiées ou retirées sans préavis, comme indiqué dans Opérations expérimentales.
Et ensuite ?
Section intitulée « Et ensuite ? »- Consultez la référence API pour le marqueur de stabilité actuel, ainsi que le schéma de requête et de réponse de chaque opération.
- Consultez Getting Started pour le modèle de sécurité et le choix d’un flux OAuth.