C# Academy · Leçon

Stratégies de versionnement d’API

Versionnez via l’URL, l’en-tête et la chaîne de requête.

Stratégies de versionnement d’API est une leçon C# Academy gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage C# Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours C# Academy comprend 4 leçons au total.

Pourquoi versionner une API ?

Une fois que des clients dépendent de votre API, vous ne pouvez plus rompre son contrat. Le versionnage vous permet de déployer des changements incompatibles dans une nouvelle version, tandis que les anciens clients continuent de fonctionner avec l’ancienne.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Versionnage dans le chemin de l’URL

La stratégie la plus visible place la version dans le chemin. Elle est sans ambiguïté et facilite le routage, la consultation et la mise en cache.

GET /api/v1/products
GET /api/v2/products

Versionnage dans la chaîne de requête

La version est transmise sous forme de paramètre de requête. Les URL restent stables et l’absence de paramètre peut entraîner l’utilisation de la version la plus récente ou d’une version fixe.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Versionnage dans un en-tête

Un en-tête de requête personnalisé transporte la version, ce qui préserve la lisibilité de l’URL. En contrepartie, celle-ci est invisible dans la barre d’adresse d’un navigateur et plus difficile à tester manuellement.

GET /api/products
X-Api-Version: 2.0

Versionnage par type de média

Également appelé négociation de contenu. La version est intégrée au type de média de l’en-tête Accept. C’est l’option la plus conforme à REST, mais aussi la moins facile à découvrir.

GET /api/products
Accept: application/json;v=2.0

Comparer les stratégies

Chaque stratégie établit un compromis entre la facilité de découverte et la lisibilité de l’URL :

Chemin de l’URL : le plus facile à découvrir, mais encombre les URL.
Chaîne de requête : URL stables et valeurs par défaut faciles à définir.
En-tête : URL claires, mais informations masquées dans les navigateurs.
Type de média : REST le plus pur, mais le plus difficile à utiliser.

// Many teams pick URL path for public APIs

Versionnage sémantique des API

Les versions d’API sont généralement uniquement majeures (v1, v2). Réservez les versions mineures aux changements additifs et rétrocompatibles que les anciens clients peuvent ignorer.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Obsolescence

Ne supprimez jamais brusquement une ancienne version. Marquez-la comme obsolète, annoncez une date de fin de prise en charge et indiquez-la aux clients via des en-têtes.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Version par défaut

Décidez de ce qui se passe lorsqu’un client n’envoie aucune version. Les choix courants sont les suivants : utiliser la plus récente, utiliser v1 ou rejeter la requête. Une définition explicite évite les surprises.

// Strategy: unversioned request -> treat as v1.0

Versionner les bons éléments

Versionnez le contrat (routes, structures des requêtes et des réponses), et non les détails d’implémentation internes. Un point de terminaison v2 peut partager la majeure partie de la logique métier avec v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Mélanger les stratégies

La bibliothèque de versionnage d’ASP.NET Core peut lire la version depuis plusieurs sources à la fois, ce qui permet aux clients de choisir la méthode qui leur convient. Vous allez la configurer ensuite.

// Accept version from URL OR header OR query

Vérification rapide

Testez votre compréhension des stratégies de versionnage.

Récapitulatif

Vous avez passé en revue les stratégies de versionnage des API :

Chemin de l’URL, chaîne de requête, en-tête et type de média.
Chacune établit un compromis entre la facilité de découverte et la lisibilité de l’URL.
Versionnez le contrat, rendez les versions obsolètes progressivement et définissez une valeur par défaut.

Ensuite : configurer Asp.Versioning dans ASP.NET Core.

Questions Fréquemment Posées

La leçon « Stratégies de versionnement d’API » est-elle gratuite ?

Oui — le texte complet de « Stratégies de versionnement d’API » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours C# Academy, passe à CoddyKit PRO. Le cours C# Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Stratégies de versionnement d’API » ?

Versionnez via l’URL, l’en-tête et la chaîne de requête. Tu pratiques C# Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer C# Academy ?

Aucune expérience préalable n'est requise. C# Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « Stratégies de versionnement d’API » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon C# Academy ?

Oui. Chaque leçon C# Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à C# Academy