Versionnement des API et compatibilité ascendante
Apprenez des stratégies pour faire évoluer les API sans interrompre les clients existants, notamment les schémas de versionnement et les règles de compatibilité.
Versionnement des API et compatibilité ascendante est une leçon System Design Basics for Backend Developers gratuite sur CoddyKit. Ceci est la leçon 4 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 System Design Basics for Backend Developers, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours System Design Basics for Backend Developers comprend 4 leçons au total.
Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.
Why APIs Must Evolve Carefully
Once an API has clients, you cannot freely change it. Renaming a field or removing an endpoint can break every consumer. Versioning lets you evolve the API while existing clients keep working.
Breaking vs Non-Breaking Changes
Know the difference:
- Non-breaking: adding a new optional field, adding a new endpoint
- Breaking: removing a field, renaming a field, changing a type, making an optional field required
Non-breaking changes can ship without a new version; breaking ones cannot.
URI Versioning
The most visible scheme puts the version in the path. It is simple and cache-friendly, and clients can clearly see which version they call.
GET /v1/users/42
GET /v2/users/42Header Versioning
Alternatively, clients request a version via a header. This keeps URIs clean and treats the version as part of content negotiation.
GET /users/42
Accept: application/vnd.myapp.v2+jsonQuery Parameter Versioning
A lighter approach uses a query parameter, e.g. ?version=2. It is easy to test in a browser but mixes versioning with regular parameters and can complicate caching.
GET /users/42?version=2Semantic Versioning
SemVer (MAJOR.MINOR.PATCH) communicates intent:
- MAJOR: breaking changes
- MINOR: new backward-compatible features
- PATCH: backward-compatible fixes
For public HTTP APIs, the MAJOR number usually maps to the URI version.
Additive Change Discipline
The cheapest versioning is not needing a new version. Follow the additive rule: only add, never remove or rename. Clients ignore unknown fields, so adding is safe.
{
"id": 42,
"name": "Ada",
"email": "ada@x.com"
}
// Later, safely add:
{
"id": 42,
"name": "Ada",
"email": "ada@x.com",
"created_at": "2026-01-01"
}Deprecation, Not Deletion
When you must retire something, deprecate first. Mark it in docs, send a Deprecation or Sunset header, and give clients a clear timeline before removal.
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: </v2/users>; rel="successor-version"Versioning gRPC and GraphQL
It is not just REST. In gRPC, never reuse or renumber protobuf field tags — that breaks the wire format. In GraphQL, the convention is no versions at all: add fields and use the @deprecated directive on old ones.
Supporting Multiple Versions
Running several versions at once has a cost. Strategies include translating old requests to the new internal model, or routing versions to different handlers. Limit how many versions you support and sunset old ones on schedule.
Designing for Change Up Front
Reduce future pain by designing for evolution: prefer objects over bare values so you can add fields, avoid leaking internal enums, and document a clear compatibility contract from day one.
Quick Check
Test your understanding of API versioning.
Recap
You learned how to evolve APIs safely:
- Distinguish breaking from non-breaking changes
- URI, header, and query parameter versioning schemes
- SemVer and the additive-change discipline
- Deprecate with Sunset headers before deleting
- gRPC tag stability and GraphQL's deprecation approach
Questions Fréquemment Posées
La leçon « Versionnement des API et compatibilité ascendante » est-elle gratuite ?
Oui — le texte complet de « Versionnement des API et compatibilité ascendante » 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 System Design Basics for Backend Developers, passe à CoddyKit PRO. Le cours System Design Basics for Backend Developers comprend 4 leçons au total.
Qu'est-ce que j'apprendrai dans « Versionnement des API et compatibilité ascendante » ?
Apprenez des stratégies pour faire évoluer les API sans interrompre les clients existants, notamment les schémas de versionnement et les règles de compatibilité. Tu pratiques System Design Basics for Backend Developers 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 System Design Basics for Backend Developers ?
Aucune expérience préalable n'est requise. System Design Basics for Backend Developers 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 4 sur 4.
Combien de temps prend la leçon « Versionnement des API et compatibilité ascendante » ?
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 System Design Basics for Backend Developers ?
Oui. Chaque leçon System Design Basics for Backend Developers 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
- Principes de conception des API RESTful
- GraphQL et gRPC
- Files de messages et architecture pilotée par les événements
- Versionnement des API et compatibilité ascendante