§ 01
Gestion par URL
Préfixe /v1, /v2 dans les URLs. Stratégie la plus lisible, cache réseau facile, utilisable sans configuration particulière.
- /v1, /v2 clairs
- Cache compatible
- Sans en-têtes spéciaux
- URLs séparées
§ 05 / 05 — VERSIONING D'API
Faire évoluer une API sans rompre les intégrations.
Stratégies de gestion des versions honnêtes : URL (/v1, /v2), en-têtes signalant les fins de vie, politiques de retrait annoncées à l'avance, migration accompagnée des clients. Vos intégrateurs ont le temps de migrer, pas de mauvaises surprises.
§ 01 — Le problème
Le problème.
Sans expert
- Champ obligatoire ajouté — Vous ajoutez un champ obligatoire — 20 intégrations cassent instantanément.
- Ressource renommée — Vous renommez une ressource pour « faire propre » — tout le monde doit coder en urgence.
- Aucun journal des nouveautés — Pas d'annonce, pas de période de grâce : les clients découvrent par une erreur en production.
- Intégrateurs inconnus — Impossible de savoir qui consomme quoi — vous cassez à l'aveugle.
- Support par ticket énervé — Les clients apprennent la migration via un ticket support énervé le lundi matin.
Avec Vulcain
- Gestion par url claire (/v1
- /v2)
- En-têtes techniques standards signalant les fins de vie
- Annoncées 12 mois à l'avance
- Journal des nouveautés versionné
- Statistiques d'usage par version pour identifier les retardataires
- Guide de migration automatique.
§ 02 — Ce qui est livré
Ce qui est livré.
§ 02
Signalement des retraits
En-têtes techniques standards signalant la date de retrait et le lien vers la nouvelle version, dans chaque réponse des points d'accès obsolètes.
- Date de retrait
- Marqueur obsolète
- Lien vers documentation
- Guide de migration
§ 03
Coexistence v1/v2
Les deux versions tournent en parallèle. Même code métier, deux présentations distinctes pour les consommateurs.
- Deux URLs
- Même métier
- Présentations séparées
- Tests par version
§ 04
Statistiques d'usage
Suivi des appels par version, par client. Tableau de bord qui montre qui consomme quoi. Permet de relancer les retardataires avant la date limite.
- Appels par version
- Top consommateurs
- Tableau de bord
- Export CSV
§ 05
Journal des nouveautés
Journal structuré versionné avec le code, abonnements par flux RSS et email pour les consommateurs enregistrés.
- Journal structuré
- Flux RSS
- Notifications email
- Marquage des ruptures
§ 06
Guide migration auto
Comparaison entre v1 et v2 générée automatiquement : quels points d'accès ont bougé, quels champs sont renommés, exemples de migration.
- Comparaison automatique
- Exemples avant/après
- Liste de vérification
- Support 3 mois
src/EventListener/DeprecationHeaderListener.php
php
final class DeprecationHeaderListener
{
public function __construct(
private readonly \DateTimeImmutable $sunset,
) {}
public function onResponse(ResponseEvent $event): void
{
$request = $event->getRequest();
if (!str_starts_with($request->getPathInfo(), '/api/v1')) {
return;
}
$response = $event->getResponse();
$response->headers->set('Deprecation', 'true');
$response->headers->set('Sunset', $this->sunset->format(\DateTime::RFC7231));
$response->headers->set('Link', '</api/v2/>; rel="successor-version"');
}
}Un écouteur ajoute les en-têtes techniques standards sur tous les points d'accès v1, pour signaler la date de retrait à 12 mois.
§ 04 — Tarifs & délais
§ 01
Mise en place de la gestion des versions
Votre API actuelle devient /v1, structure en place pour les versions futures, en-têtes de fin de vie, journal des nouveautés.
- Structure /v1
- En-têtes de fin de vie
- Journal des nouveautés
- Statistiques simples
- Guide équipe
§ 02
Passage v1 → v2
Conception de la v2 avec les évolutions cassantes souhaitées, coexistence v1/v2, guide de migration, support des intégrateurs.
- Conception v2
- Coexistence
- Guide de migration
- Notifications clients
- Support 3 mois
§ 03
Gouvernance API continue
Revue trimestrielle : évolutions cassantes à venir, état de santé des versions, relance des intégrateurs en retard.
- Revue trimestrielle
- Plan des ruptures
- État de santé
- Relance intégrateurs
Tarifs sur devis après cadrage · forfait ou régie selon le format
§ 04 — Questions fréquentes
Questions sur le versioning.
§ 01 URL, en-tête ou sous-domaine ?
URL (/v1, /v2) dans 90 % des cas : lisible, simple, compatible avec les caches. En-tête spécifique pour les clients sophistiqués. Sous-domaine (v2.api.mycompany.com) pour les refontes majeures.
§ 02 Quand sortir une nouvelle version majeure ?
Seulement pour des évolutions cassantes inévitables : renommage de ressources centrales, changement de modèle de données, évolution majeure de l'authentification. Les ajouts non cassants (nouveaux champs) ne nécessitent jamais de v2.
§ 03 Combien de temps garder l'ancienne version ?
Minimum 12 mois après l'annonce du retrait. Pour des API critiques (finance, santé), plutôt 24 mois. En-têtes signalant le retrait obligatoires dès l'annonce.
§ 04 Comment savoir qui consomme quoi ?
Journaux structurés avec la version, tableau de bord. Pour les API avec clés : suivi par client. Pour les API publiques : par navigateur + IP. Export CSV pour relances.
§ 05 Évolution cassante urgente malgré tout ?
Si c'est une faille de sécurité, pas le choix : annonce urgente, période de grâce réduite (2 à 4 semaines), support renforcé aux intégrateurs. Sinon, toujours nouvelle version majeure.
§ 06 Vous maintenez combien de versions en parallèle ?
Idéalement 2 (version actuelle + précédente). 3 en transition. Au-delà, la charge mentale explose. Si les intégrateurs traînent, on aligne les incitations : v1 avec limitation d'appels agressive, tarification différenciée.
§ 06 — Voir aussi
§ 08 — Mettre la forge au travail
15 minutes pour savoir
15 minutes pour savoir
si on peut forger ensemble.
Un appel, pas un formulaire de 12 champs. Vous m'expliquez votre besoin, je vous dis honnêtement si je suis la bonne personne, on repart avec une prochaine étape claire.
-
01
Compte-rendu écrit et estimation envoyés sous 24 h.
-
02
Aucun engagement. Aucune relance commerciale.
-
03
Si ce n'est pas pour moi, je vous oriente vers un confrère.