Versionnement des contrats publics
Comprenez ce que représente la version v1 , quels enrichissements un client doit tolérer et quelles modifications constituent au contraire une rupture de contrat du point de vue d’un consommateur.
La frontière REST publique est /v1
Les ressources REST publiques sont exposées sous https://api.ormuz.io/v1/. Ce préfixe identifie la famille de contrat HTTP consommée par votre intégration ; il ne correspond ni à la révision d’un processus, ni à la version d’une extension, ni à la révision d’un Agent ou d’une Decision.
Une Process revision, une Agent revision ou une Decision revision fige le comportement d’un artefact déployable. /v1 décrit la forme de l’interface machine utilisée pour créer, lire ou exécuter ces artefacts.
Distinguer enrichissement et rupture
| Évolution | Impact consommateur | Comportement recommandé |
|---|---|---|
| Nouveau champ optionnel dans une réponse | Enrichissement | Ignorer les champs inconnus que votre client n’utilise pas. |
| Nouveau endpoint ou nouvelle ressource | Enrichissement | Aucun impact tant que votre intégration ne l’appelle pas. |
| Nouveau type d’événement | Enrichissement du catalogue | Abonnez-vous explicitement aux types nécessaires plutôt qu’à tous les événements. |
| Nouvelle valeur d’enum | Peut surprendre un client fermé | Prévoir une branche « valeur inconnue » lorsque l’enum représente un état provider ou extensible. |
| Champ supprimé, renommé ou devenu obligatoire | Rupture pour les clients qui en dépendent | Ne pas assimiler cette modification à un enrichissement compatible. |
| Type, unité ou sémantique d’un champ modifié | Rupture de contrat | Traiter comme un changement de version ou une migration explicite. |
| Identifiant d’événement renommé | Rupture du filtrage | Mettre à jour explicitement les abonnements et consommateurs concernés. |
Les identifiants, curseurs de pagination, tokens et références provider doivent être traités comme des valeurs opaques. Un client qui dépend de leur structure interne crée sa propre incompatibilité.
Compatibilité des événements
Les identifiants de type — par exemple invoice.paid ou extension.stripe.payment_intent.succeeded — sont la clé de filtrage publique. Le payload d’un événement est un snapshot ; il peut s’enrichir avec de nouveaux champs publics sans que votre consommateur ait besoin de les connaître.
- Ignorez les champs inconnus.
- Ne supposez pas un ordre global entre tous les types d’événements.
- Relisez l’objet courant via l’API lorsque la décision dépend de son état actuel plutôt que du seul snapshot.
- Utilisez des abonnements explicites en production lorsque votre traitement dépend d’un contrat précis.
Le catalogue des événements est la référence pour les types plateforme ; chaque extension documente ses propres événements dans sa section d’intégration.
Construire un client robuste
- Réponses JSON : lire les champs dont vous avez besoin et ignorer les autres.
- Enums : prévoir un comportement sûr pour une valeur non reconnue au lieu de la considérer comme un succès.
- Pagination : utiliser
has_moreou le curseur documenté, sans fabriquer le prochain curseur. - IDs : les stocker comme chaînes opaques.
- Montants : respecter
common.amountet la devise associée ; ne pas convertir en flottant. - Dates : conserver les timestamps ISO 8601 avec timezone et distinguer une date civile d’un datetime.
Les artefacts ont leur propre versionnement
Les processus, Forms, Agents et Decisions utilisent des révisions immuables pour garantir qu’une exécution peut être rattachée à la configuration exacte qui l’a produite. Cette mécanique est indépendante de la version HTTP.
| Concept | Version figée | Documentation |
|---|---|---|
| Processus | Process revision | Définitions, révisions et instances |
| Form | Form revision | Forms |
| Decision | Decision revision | Decisions |
| Agent | Agent revision | Agents |
Suivre le contrat courant
La référence API, le catalogue des événements et les pages d’intégration sont les sources publiques à jour du contrat actuel. Les catalogues structurels de la documentation sont générés depuis les registres du produit afin qu’un endpoint, node ou événement nouvellement exposé ne dépende pas d’une liste manuelle partielle.
Lors d’une mise à jour d’intégration, comparez les champs et types réellement consommés par votre application avec le contrat courant. Une modification qui change leur signification doit être traitée comme une migration explicite, même si le JSON reste syntaxiquement valide.