Quelles sont les principales stratégies de versioning d'API, et comment déprécier une version ?

Question

IT Interview Practice · Accepted Answer

Le versioning vous permet de faire évoluer une API avec des **breaking changes** sans casser les clients existants. Il existe trois stratégies principales, plus un processus de dépréciation.

## Les trois stratégies

**1. URI versioning** — la version est dans le chemin.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
La plus simple et la plus visible ; facile à router, cacher et tester dans un navigateur. Inconvénient : cela viole techniquement « l'URI identifie une ressource » (le même user a maintenant deux URL). C'est de loin le choix le plus courant (GitHub, Stripe historiquement).

**2. Custom header versioning** — la version voyage dans un header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Garde les URL propres mais est invisible dans un navigateur et plus difficile à cacher.

**3. Media-type (content negotiation) versioning** — la version dans `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Le plus « RESTful » (l'URL de la ressource est stable ; seule sa représentation est versionnée), mais le moins accessible pour les consommateurs.

## Ce qui compte comme breaking

```text
BREAKING      → supprimer/renommer un champ, changer un type, changer l'auth, durcir la validation
NON-BREAKING  → ajouter un nouveau champ optionnel, ajouter un nouveau endpoint, ajouter une valeur d'enum*
```
Seuls les breaking changes nécessitent une nouvelle version ; ajoutez les changements non-breaking à la version actuelle.

## Processus de dépréciation

1. **Annoncer** avec des dates dans la doc et le changelog.
2. **Signaler au runtime** avec des headers pour que les clients le remarquent programmatiquement :
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Surveiller** l'usage de l'ancienne version et contacter les appelants restants.
4. **Sunset** seulement après que l'usage soit tombé proche de zéro.

## Pourquoi c'est important

Les recruteurs posent cette question pour voir si vous pouvez faire grandir une API en production sans casser les clients qui en dépendent — une préoccupation opérationnelle réelle, pas théorique. Les meilleures réponses font deux distinctions : d'abord, que **la plupart des changements sont non-breaking** et ne devraient déclencher aucun bump de version (les changements additifs vont dans la version actuelle), réservant le versioning aux changements réellement breaking ; ensuite, que la *stratégie* importe moins que le *processus* — un calendrier de dépréciation clair avec des headers `Deprecation`/`Sunset` et une surveillance de l'usage est ce qui protège réellement les consommateurs. L'URI versioning l'emporte en pratique pour sa visibilité et son support par l'outillage, mais connaître les compromis (header et media-type gardent les URL stables et sont plus RESTful, au prix de la découvrabilité) montre que vous comprenez l'espace de conception plutôt que de simplement copier `/v1/` par mimétisme.

Les trois stratégies

Ce qui compte comme breaking

Processus de dépréciation

Pourquoi c'est important

Questions connexes