Aller au contenu
Documentation

APIGestion des versions par RTC

Tout ce qui se trouve sous /v1 Modifications uniquement de manière additive. RTC peut ajouter :

  • nouvelles routes, champs de requête facultatifs et paramètres de requête ;
  • nouveaux champs de réponse, codes d’erreur, types d’événements de webhook et valeurs d’énumération ;
  • Nouveaux en-têtes de réponse.

Créez des clients qui ignorent les champs inconnus et traitent un code d’erreur inconnu comme le code générique de son statut HTTP. RTC ne supprime ni ne renomme aucun champ, ne modifie ni son type ni sa signification, ne rend pas obligatoire une entrée facultative, ni ne réutilise un code d’erreur sous /v1.

Une modification rompant avec la compatibilité ascendante est publiée sous la forme d’une nouvelle version majeure, /v2. Les deux versions fonctionnent alors en parallèle pendant au moins 12 mois avant /v1 est retirée, comme indiqué sur ce site.

Définissez les formats de réponse avec RTC-Version

Section intitulée « Définissez les formats de réponse avec RTC-Version »

Certaines améliorations modifient la forme d’une réponse sans en changer la signification, comme par exemple la enveloppe d’erreur structurée. Elles sont activables au cas par cas pour chaque requête, avec un en-tête de version daté :

RTC-Version: 2026-11-01
VersionModifications
aucuneFormes d’origine. Les erreurs sont { "error": "<message>", "code"? }.
2026-11-01Les erreurs utilisent l’enveloppe { "error": { code, message, details?, requestId, retryable, docUrl } }.

RTC applique la version la plus récente, dont la date de publication n’est pas postérieure à celle de votre envoi, et la reprend dans le RTC-Version En-tête de réponse. Une date antérieure à la première version conserve les formats d’origine. Fixez la version sur laquelle votre code a été écrit et modifiez-la délibérément lors de la mise à niveau.

Épinglez les charges utiles des webhooks avec apiVersion

Section intitulée « Épinglez les charges utiles des webhooks avec apiVersion »

Chaque Point de terminaison du webhook dispose d’un apiVersion qui corrige l’ enveloppe qu’elle reçoit, indépendamment des en-têtes de requête :

apiVersionEnveloppe
legacy{ id, type, createdAt, projectId, data }, l’ancien webhook unique a été migré vers un point de terminaison
2026-11-01{ id, type, apiVersion, createdAt, tenantId, projectId, roomId?, data }, valeur par défaut pour les nouveaux points de terminaison

Événement data évolue de manière additive, à l’instar de API. Pour faire passer un destinataire à une version plus récente de la charge utile, ajoutez un deuxième point de terminaison avec la nouvelle version, modifiez votre traitement, puis supprimez l’ancien point de terminaison.

GET /v1/capabilities rapports contractVersion, qui évolue chaque fois que le contrat client intègre de nouvelles fonctionnalités. SDKs peut l’utiliser pour activer de nouvelles fonctionnalités uniquement lorsque l’API les prend déjàAPI en charge.

Les routes client de RTC sont décrites dans OpenAPI 3.1, générées à partir des schémas utilisés par l’API pour validerAPI les requêtes et vérifiées par rapport au code à chaque modification. Le fichier se trouve docs/openapi/v1.yaml dans le référentiel de la plateforme RTC . Contact CHAMPREP à recevoir le fichier actuel pour la génération du client ; cette référence et le API référence restent dans la documentation publique.