Stratégies de Versioning d'API

Les stratégies de versioning d'API assurent une évolution fluide des APIs tout en maintenant la compatibilité. GitScrum aide les équipes à suivre les changements d'API, les décisions de versioning et la migration des clients à travers les cycles de développement.

Cycle de Vie du Versioning API

Concevoir API ──► Implémenter v1 ──► Planifier ──► Sortir v2 ──► Déprécier v1 ──► Retirer v1
      │                │          Changements        │              │               │
      ▼                ▼              │               ▼              ▼               ▼
  Recueil des     Première       Analyse des    Mises à jour    Période de    Fin de vie
  Exigences       Release        Changements   Rétrocompat.     Sunset &      Communication
                & Documentation   Cassants                      Migration

Stratégies de Versioning

Comparaison des Approches

Versioning URI (Recommandé)

VERSIONING DANS L'URI
═════════════════════

STRUCTURE :
├── /api/v1/users
├── /api/v1/projects
├── /api/v2/users (nouvelle version)
└── /api/v2/projects

AVANTAGES :
├── Explicite et clair
├── Facile à router au niveau serveur
├── Facile à cacher
├── Visible dans les logs et monitoring
└── Simple à tester manuellement

IMPLÉMENTATION :
├── Routes séparées par version
├── Contrôleurs peuvent être partagés
├── Middleware de version si besoin
└── Redirection de version par défaut

Versioning par Header

VERSIONING PAR HEADER
═════════════════════

REQUÊTE :
GET /api/users HTTP/1.1
Host: api.exemple.com
Accept: application/vnd.exemple.v2+json

OU :
GET /api/users HTTP/1.1
Accept-Version: v2

AVANTAGES :
├── URLs stables
├── Négociation de contenu propre
└── Respecte les principes REST

INCONVÉNIENTS :
├── Moins visible
├── Plus difficile à tester dans le navigateur
├── Oublié facilement par les clients
└── Documentation plus complexe

Évolution de l'API

Changements Non-Cassants

CHANGEMENTS SÛRS (PAS DE NOUVELLE VERSION) :
════════════════════════════════════════════

✅ AJOUTER UN CHAMP OPTIONNEL :
{
  "id": 123,
  "name": "Jean",
  "avatar": "..." ← Nouveau, optionnel
}

✅ AJOUTER UN ENDPOINT :
GET /api/v1/users/{id}/preferences ← Nouveau

✅ AJOUTER UN PARAMÈTRE QUERY OPTIONNEL :
GET /api/v1/users?include_deleted=true ← Nouveau

✅ AJOUTER UNE VALEUR D'ÉNUMÉRATION :
status: "active" | "inactive" | "pending" ← Nouveau

✅ ASSOUPLIR UNE VALIDATION :
max_length: 100 → 200 (plus permissif)

Changements Cassants

CHANGEMENTS QUI NÉCESSITENT NOUVELLE VERSION :
══════════════════════════════════════════════

❌ SUPPRIMER UN CHAMP :
v1: { "id": 123, "name": "Jean", "legacy_id": "abc" }
v2: { "id": 123, "name": "Jean" } ← legacy_id supprimé

❌ RENOMMER UN CHAMP :
v1: { "user_name": "jean" }
v2: { "username": "jean" }

❌ CHANGER UN TYPE :
v1: { "count": "123" } (string)
v2: { "count": 123 } (number)

❌ RENDRE UN CHAMP OPTIONNEL REQUIS :
v1: POST /users { "name": required, "bio": optional }
v2: POST /users { "name": required, "bio": required }

❌ CHANGER LA STRUCTURE DE RÉPONSE :
v1: { "data": [...] }
v2: { "results": [...] }

Gestion du Cycle de Vie

Phases de Version

CYCLE DE VIE D'UNE VERSION API
══════════════════════════════

    ┌─────────┐
    │  BETA   │  Tests, feedback, changements possibles
    └────┬────┘
         │
    ┌────▼────┐
    │ STABLE  │  Production, contrat figé
    └────┬────┘
         │ (nouvelle version sort)
    ┌────▼────┐
    │DÉPRÉCIÉ │  Fonctionne mais sunset annoncé
    └────┬────┘
         │ (après période de transition)
    ┌────▼────┐
    │ RETIRÉ  │  Plus disponible
    └─────────┘

Communication de Dépréciation

HEADERS DE DÉPRÉCIATION
═══════════════════════

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.exemple.com/v2/users>; rel="successor-version"

CONTENU DU BODY (optionnel) :
{
  "_deprecated": {
    "message": "Cette version sera retirée le 31 Dec 2024",
    "migration_guide": "https://docs.exemple.com/migrate-v1-v2",
    "successor": "/api/v2/users"
  },
  "data": { ... }
}

Planification de Migration

Timeline Recommandée

CALENDRIER DE TRANSITION
════════════════════════

MOIS 1-2 : PRÉPARATION
├── Développer v2
├── Tests internes
├── Documentation migration
└── Communiquer aux clients

MOIS 3-4 : PÉRIODE BETA
├── v2 disponible en beta
├── v1 toujours stable
├── Feedback des early adopters
└── Ajustements v2

MOIS 5-6 : DÉPRÉCIATION
├── v2 devient stable
├── v1 marquée dépréciée
├── Headers Deprecation/Sunset
└── Support migration active

MOIS 7-12 : TRANSITION
├── v1 fonctionne toujours
├── Monitoring usage v1
├── Relances clients v1
└── Support migration

MOIS 13+ : SUNSET
├── v1 retirée
├── Retourne 410 Gone
└── Message de migration

Suivi dans GitScrum

TÂCHES DE VERSIONING DANS GITSCRUM
══════════════════════════════════

EPIC : Migration API v1 → v2

STORIES :
├── API-100 : Concevoir changements v2
├── API-101 : Implémenter nouveaux endpoints v2
├── API-102 : Écrire guide de migration
├── API-103 : Configurer headers de dépréciation
├── API-104 : Notifier clients par email
├── API-105 : Monitorer adoption v2
├── API-106 : Identifier clients v1 restants
├── API-107 : Contacter clients v1 directement
└── API-108 : Retirer v1

LABELS :
├── api-versioning
├── breaking-change
├── client-migration
└── deprecation

Bonnes Pratiques

Conseils de Versioning

Erreurs à Éviter

ANTI-PATTERNS DE VERSIONING
═══════════════════════════

❌ PAS DE VERSION DÈS LE DÉPART
└── Difficile à ajouter après coup

❌ TROP DE VERSIONS ACTIVES
└── Maintenance coûteuse

❌ PÉRIODE DE TRANSITION TROP COURTE
└── Clients mécontents

❌ PAS DE COMMUNICATION
└── Surprises et friction

❌ CHANGEMENTS CASSANTS SANS NOUVELLE VERSION
└── Casser les clients existants

Solutions Connexes

• Meilleures pratiques de conception d'API
• Meilleures pratiques de développement d'API
• Développement API-first
• Patterns de passerelle API