Politique de versions

L’API se versionne par date. Une version fixe la forme des réponses et la manière dont l’API se comporte : le code que vous écrivez contre elle continue de marcher tant que vous la gardez.

Choisir sa version

Je veux…	Comment
Savoir quelle version j’utilise	La version de votre organisation, fixée à sa création sur la plus récente. Chaque événement la porte dans `api_version`
Fixer la version d’une requête	L’en-tête `Ophelix-Version: 2026-11-01`. Une version inconnue répond `api_version_invalid`
Savoir ce qu’une version change	Son entrée au journal des changements
Garder la même version partout	Les bibliothèques envoient la version avec laquelle elles sont publiées, quelle que soit celle de l’organisation

Ce qui ne demande pas de nouvelle version

Une réponse est additive : dans une version, un champ n’est jamais retiré ni renommé. Ces changements arrivent sans prévenir, et votre code doit les accepter :

une nouvelle route, ou une nouvelle ressource ;
un nouveau champ dans une réponse ou dans un objet d’événement ;
un nouveau paramètre facultatif ;
un nouveau type d’événement : un point de terminaison ne le reçoit que s’il l’écoute par un joker, comme claim.* ou * ;
un nouveau code d’erreur : le statut HTTP garde son sens, traitez un code inconnu d’après lui ;
l’ordre des champs dans une réponse, la longueur et la forme d’un identifiant, le texte d’un message d’erreur.

Lisez une réponse en ignorant les champs que vous ne connaissez pas, et ne comparez jamais un message : comparez le code.

Ce qui demande une nouvelle version

retirer ou renommer un champ, une route ou un paramètre ;
changer le type, le format ou le sens d’un champ ;
rendre obligatoire un paramètre qui ne l’était pas, ou refuser une valeur acceptée jusque-là ;
ajouter une valeur à un champ énuméré d’une réponse, comme un statut ;
changer le statut HTTP ou le code d’erreur rendu dans un même cas ;
changer la forme d’un événement d’un type existant.

Un changement cassant sort dans une nouvelle version datée, avec son entrée au journal. Une version publiée ne reçoit plus que des ajouts.

Durée de vie d’une version

Une seule version existe aujourd’hui, 2026-11-01, sans fin annoncée. La durée pendant laquelle une version reste servie après la sortie de la suivante sera fixée et publiée sur cette page avant la deuxième version. La fin d’une version s’annoncera au journal des changements, avec sa date.

Passer à une nouvelle version

Lisez son entrée au journal : elle dit ce qui casse et quoi changer.
Essayez-la requête par requête, en mode test, avec Ophelix-Version, ou l’option de version d’appel des bibliothèques (api_version en PHP, apiVersion en Node).
Adaptez votre réception d’événements : un événement garde la version sous laquelle il a été produit.
Mettez à jour votre bibliothèque : chaque publication envoie la version avec laquelle elle sort.