SemVer (Semantic Versioning) est un contrat, pas une décoration. Une API mal versionnée force ses consommateurs à casser leur code — ou à ne jamais mettre à jour. Les 4 règles à appliquer strictement en 2025.
Rappel : MAJOR.MINOR.PATCH. MAJOR = breaking. MINOR = nouvelle feature backward-compatible. PATCH = fix. Point.
Les 4 règles opérationnelles
- Un champ qu'on retire => MAJOR. Sans exception.
- Un champ qu'on ajoute => MINOR, avec valeur par défaut si obligatoire dans une v ultérieure.
- Un champ dont le type change => MAJOR (même de nullable à non-nullable).
- Un endpoint qu'on renomme => MAJOR, avec l'ancien maintenu 6 mois minimum.
Deprecation propre
Annoncer 3 mois avant, doc explicite, header Deprecation etSunset : RFC 8594. Vos consommateurs vous remercient.
Versionner dans l'URL ou header ?
/v1/users— plus simple, plus lisible dans les logsAccept: application/vnd.mycompany.v1+json— plus « pur », moins lisible
Défaut : URL. Sauf raison forte, plus simple à débuguer.
Un breaking change annoncé 3 mois avant est un non-événement. Le même breaking change sans préavis, c'est votre plus gros client qui vous quitte.
On refont votre versioning ?
En 30 minutes on peut cadrer votre stratégie. Réservez un créneau. À lire : API REST ou GraphQL.