API ecentic : gestion des versions.
La version est dans le chemin. Une intégration qui fixe une version conserve le contrat pour lequel elle a été conçue et ne le perd jamais sans avertissement.
Versionnement par chemin d’URL · Préavis de 180 jours · En-têtes Deprecation et Sunset
Fonctionnement des versions
Un seul numéro, dans le chemin, modifié uniquement en cas de changement incompatible.
La version actuelle est v1, servie sur /api/v1. Chaque réponse renvoie également la version dans un en-tête API-Version, afin qu’un client suivant une redirection ou un lien puisse confirmer avec quoi il communique réellement.
Ajouter à la même version
Les changements additifs sont déployés au sein d’une même version : nouveaux points d’accès, nouveaux champs de requête optionnels, nouveaux champs dans une réponse existante. Considérez les champs de réponse inconnus comme de la compatibilité ascendante, et non comme une erreur.
Créer un nouveau chemin de version
Un changement qui supprime un champ, le renomme, restreint un type ou modifie la signification d’une valeur existante est un changement incompatible et est déployé sous un nouveau chemin de version à côté de l’ancien — jamais à sa place.
Dépréciation et fin de vie
Deux en-têtes standard et un délai suffisant pour agir en conséquence.
Sélectionnez un en-tête pour voir ce qu’il indique à votre client.
Dépréciation annoncée
Une version est dépréciée
Chaque réponse provenant d’une version dépréciée inclut cet en-tête. Il annonce la dépréciation conformément à la RFC 9745.
Date de retrait annoncée
Une date de retrait est fixée
Les réponses incluent également cet en-tête lorsqu’une date de retrait est fixée. La RFC 8594 définit la date à laquelle la version cesse de répondre.
Version de remplacement liée
La version de remplacement est identifiée
En plus de la date de retrait, un Link avec rel="successor-version" oriente votre client vers la version de remplacement.
Valeurs d’en-tête fournies à titre d’exemple, pas comme annonce de retrait.
Ce qui n’est pas versionné
Les documents de découverte suivent à la place la version de leur propre protocole.
Les documents de découverte .well-known sont versionnés selon le protocole qu’ils implémentent, et non selon la version de l’API ecentic — le profil UCP porte une version UCP, la fiche serveur MCP porte une version de protocole, et ainsi de suite. Lire la version dans le document lui-même est toujours correct ; l’inférer à partir de la version de l’API ecentic ne l’est pas.
- Contrat d’API ecentic
- /api/v1
- API-Version: 1
- Contrat du protocole de découverte
- .well-known
- Lire la version dans le document