Aller au contenu

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

01

Fonctionnement des versions

Un seul numéro, dans le chemin, modifié uniquement en cas de changement incompatible.

Version de requête et de réponse fixée

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.

02

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.

Format de l’en-tête de dépréciation

Valeurs d’en-tête fournies à titre d’exemple, pas comme annonce de retrait.

03

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