Changelog API
Stratégie de versioning
Comprendre comment le versioning apparaît dans les endpoints et événements OmniLab, et comment vous préparer aux évolutions futures.
OmniLab expose aujourd'hui les marqueurs de version directement dans les chemins d'endpoint et dans les noms d'événements, par exemple /v1/oauth:token, /v1/interactions:fetchContactBookings, et des types d'événements webhook terminant par .v1.
Ce qui est versionné aujourd'hui
- les endpoints REST sous
/v1/... - les types d'événements webhook comme
reward.won.v1etbooking.created.v1 - les schémas de payload associés à ces versions
Règles pratiques de compatibilité
- traitez les nouveaux champs optionnels comme des ajouts plutôt que comme des ruptures
- traitez les changements de chemin, de champ obligatoire, ou les renommages de type d'événement comme des changements cassants
- épinglez votre logique receiver sur les noms d'événements exacts auxquels vous êtes abonné aujourd'hui
- gardez des tests de contrat en staging pour les demandes de token, les flux booking, et les signatures webhook
- validez le parsing aval avant toute promotion en production
Les marqueurs de version sont votre premier signal de compatibilité
Tant que la référence API publique continue de s'étoffer, le signal le plus clair reste la version dans le chemin ou dans le nom d'événement. Construisez vos tests et votre monitoring autour de ces points de contrat explicites.
Comment se préparer aux évolutions futures
- gardez la logique OmniLab derrière une petite couche d'adaptation
- conservez des exemples de requêtes et de réponses issus du staging
- revérifiez les flux booking et la vérification de signature webhook lorsqu'un changement est annoncé
- faites passer toute évolution par le staging avant la production