Gestion des versionsBientôt disponible

L'API Matchai gère ses versions pour qu'une intégration que vous bâtissez continue de fonctionner. Cette page explique ce qui reste pareil, ce qui peut changer sous vos pieds, et comment vous êtes avisé des changements qui demandent votre attention.

La version est dans le cheminCopier le lien de cette section

La version majeure fait partie de chaque adresse :

https://api.matchai.co/v1

Les événements webhook portent la même version dans leur corps, sous la forme "api_version": "v1". Une adresse qui commence par /v1 se comporte comme le décrit cette documentation tant que /v1 existe.

Les changements qui ne demandent pas de nouvelle versionCopier le lien de cette section

Matchai peut livrer ces changements en tout temps, sans nouvelle version et sans autre avis que le journal des modifications :

• De nouveaux points de terminaison, de nouveaux types d'événements webhook et de nouvelles portées. Une connexion n'obtient jamais une portée qui ne lui a pas été accordée.
• De nouveaux champs de requête facultatifs et de nouveaux paramètres de requête.
• De nouveaux champs dans les réponses et dans le contenu des événements webhook.
• De nouvelles valeurs dans une énumération, comme un nouveau status, une nouvelle profession ou un nouveau type d'événement.
• De nouveaux codes d'erreur et de nouveaux types d'erreurs.
• Un ordre différent des champs dans un objet JSON.
• Des changements de longueur ou de format des identifiants et des curseurs. Les identifiants sont opaques.
• La correction d'un comportement qui ne correspondait pas à cette documentation.

Écrivez donc votre client pour qu'il s'y attende :

• Ignorez les champs que vous ne connaissez pas.
• Traitez une valeur d'énumération inconnue comme « autre ». Ne plantez pas, et n'essayez pas de deviner son sens.
• N'analysez et ne construisez jamais d'identifiants. Conservez-les et renvoyez-les tels quels.
• Basez-vous sur le code d'une erreur, et rabattez-vous sur son type et son statut quand vous rencontrez un code que vous ne connaissez pas. Consultez Erreurs.
• Ignorez les événements webhook que vous ne traitez pas. Répondez 2xx et passez à autre chose.

Changements incompatiblesCopier le lien de cette section

Un changement incompatible est un changement qui peut empêcher une intégration correcte de fonctionner. Ces changements sont toujours livrés dans une nouvelle version majeure, à côté de l'ancienne :

• Retirer ou renommer un point de terminaison, un champ, un paramètre de requête, une valeur d'énumération, un type d'événement ou une portée.
• Changer le type, le format ou le sens d'un champ existant.
• Rendre obligatoire un champ de requête facultatif, ou ajouter un nouveau champ obligatoire.
• Refuser des requêtes qui étaient acceptées auparavant, en resserrant la validation.
• Changer le statut HTTP ou le code que produit une situation existante.
• Changer le fonctionnement de l'authentification, ou restreindre ce qu'une portée permet.

Une nouvelle version majeure, comme /v2, fonctionne à côté de /v1. Elle ne remplace jamais /v1 sur place, et rien n'y est transféré à votre place.

Mise en obsolescenceCopier le lien de cette section

Matchai ne retire pas une version, un point de terminaison ou un champ sans vous en aviser d'abord. Une mise en obsolescence est annoncée à l'avance dans le journal des modifications, et chaque avis indique :

• ce qui est retiré, et ce qui le remplace;
• comment faire la transition;
• ce que vous devez faire, s'il y a lieu.

L'avis est publié bien avant que l'ancien comportement soit retiré, pour vous laisser le temps de faire la transition. Lisez le journal des modifications quand vous planifiez une mise en production, et quand vous n'avez pas eu de nouvelles depuis un moment.

Le serveur MCP a ses propres versionsCopier le lien de cette section

Le serveur MCP indique sa propre version dans serverInfo.version, un numéro de version sémantique qui change quand un outil ou un champ est ajouté ou change de forme. Les outils sont décrits à l'assistant chaque fois qu'il se connecte, alors un client bien conçu découvre les nouveaux outils sans aucun changement de votre côté.