Stabilité de l'API et versionnement
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 |
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.