Le moment où le versioning d'API devient un vrai sujet n'est jamais le premier endpoint publié, c'est le jour où il faut changer la forme d'une réponse alors qu'une application mobile en production, qu'on ne contrôle plus (parce que les utilisateurs n'ont pas tous mis à jour), en dépend encore. À ce moment-là, "on va juste modifier le endpoint" devient une incompatibilité silencieuse qui casse un client qu'on ne peut même pas forcer à se mettre à jour immédiatement.

Changement compatible vs changement cassant

Toute discussion de versioning part de cette distinction, et elle est plus stricte qu'elle n'en a l'air. Ajouter un champ optionnel à une réponse JSON est généralement sans risque, à condition que les clients ignorent les champs inconnus (ce qui est le comportement par défaut de la plupart des parsers JSON, mais pas une garantie universelle). En revanche, renommer un champ, changer son type (un entier qui devient une chaîne), changer la sémantique d'un code HTTP, ou rendre obligatoire un paramètre auparavant optionnel sont des changements cassants, même s'ils semblent mineurs côté serveur.

Les trois stratégies de versioning

Versioning par URI (/api/v1/orders, /api/v2/orders) est la plus visible et la plus facile à router, mais elle fige une version dans l'URL : un client qui bookmarks ou cache une URL reste collé à cette version, et faire coexister plusieurs versions complètes du routing devient vite lourd à maintenir.

Versioning par en-tête (Accept: application/vnd.myapi.v2+json ou un en-tête custom X-API-Version: 2) garde des URLs stables, ce qui est plus propre au sens REST (l'URI identifie la ressource, pas sa représentation), mais complique le debug manuel (on ne peut plus juste coller une URL dans le navigateur) et demande une configuration de content negotiation plus fine.

Versioning par paramètre de requête (?version=2) est simple à implémenter mais pollue les URLs et se marie mal avec le caching HTTP standard, qui traite souvent la query string comme faisant partie de la clé de cache de façon incohérente selon les intermédiaires.

// Express : versioning par en-tête custom, résolu dans un middleware
app.use("/api/orders", (req, res, next) => {
  const version = req.header("X-API-Version") || "1";
  req.apiVersion = version;
  next();
});

app.get("/api/orders/:id", (req, res) => {
  const order = getOrder(req.params.id);
  if (req.apiVersion === "2") {
    return res.json(serializeOrderV2(order));
  }
  return res.json(serializeOrderV1(order));
});

En pratique, la plupart des API publiques sérieuses (Stripe, GitHub) utilisent une variante du versioning par en-tête ou par date (Stripe-Version: 2024-06-20), précisément parce que ça découple la stabilité de l'URL de l'évolution du contrat de données.

Le pattern qui évite la rupture : expand-contract

Plutôt que de remplacer un champ du jour au lendemain, le pattern expand-contract (aussi appelé parallel change) déroule le changement en trois temps : d'abord ajouter le nouveau champ en parallèle de l'ancien (expand), migrer progressivement les consommateurs vers le nouveau champ, puis seulement retirer l'ancien une fois qu'aucun client actif ne l'utilise plus (contract).

// phase "expand" : les deux champs coexistent dans la même réponse
{
  "id": "ord_123",
  "amount_cents": 4999,
  "amount": 49.99
}

L'étape de contraction ne doit jamais être une décision calendaire ("on verra dans 3 mois") mais une décision basée sur des données : instrumenter l'usage réel de l'ancien champ (logs d'accès, métriques applicatives sur quels clients envoient quel header de version) avant de le retirer.

Communiquer la dépréciation sans surprendre personne

RFC 8594 définit un en-tête Sunset standardisé, et la pratique courante ajoute un en-tête Deprecation pour signaler qu'un endpoint ou une version est en fin de vie sans attendre la date de coupure effective.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/docs/migration-v2>; rel="deprecation"

{"id": "ord_123", "amount": 49.99}

Un client bien écrit peut logger ou alerter dès qu'il reçoit Deprecation: true, ce qui donne une visibilité réelle sur l'adoption de la migration, bien plus fiable qu'un email de notification qu'une partie des équipes consommatrices ne lira jamais.

Diagnostiquer qui dépend encore de l'ancienne version

Avant de retirer quoi que ce soit, il faut savoir qui l'utilise encore, pas le supposer. Deux outils concrets : un compteur par version/endpoint dans les métriques applicatives (Prometheus avec un label api_version), et une revue des logs d'accès sur une fenêtre représentative (au moins un cycle de facturation complet si l'API expose des données financières, pour capturer les intégrations qui n'appellent l'API qu'une fois par mois).

-- requête sur une table de logs d'accès pour identifier les derniers appelants
SELECT client_id, MAX(called_at) AS last_call
FROM api_access_log
WHERE endpoint = '/api/orders' AND api_version = '1'
GROUP BY client_id
HAVING MAX(called_at) > now() - interval '30 days'
ORDER BY last_call DESC;

Tester la non-régression du contrat

Un changement de contrat non intentionnel est souvent introduit sans que personne ne l'ait voulu : un refactor qui change l'ordre de sérialisation d'un champ optionnel qui devient null au lieu d'absent, par exemple. Les tests de contrat (contract testing, avec un outil comme Pact côté consommateur-fournisseur, ou simplement un diff automatisé du schéma OpenAPI en CI) détectent ces régressions avant qu'elles n'atteignent la production, bien avant qu'un client externe ne les remonte en support.

Versionner aussi ce que le client ne voit pas directement

Tous les changements cassants ne viennent pas d'un renommage de champ dans le corps de la ressource. La forme des réponses d'erreur, la pagination par défaut, ou les seuils de rate limiting font partie du contrat au même titre que le corps de la ressource, et il est fréquent de versionner le premier sans penser à versionner le second.

// avant : une erreur sous forme de chaîne simple
{ "error": "Order not found" }

// après : une erreur structurée, qui reste un changement cassant
// pour tout client qui faisait error.toUpperCase() sur l'ancienne forme
{ "error": { "code": "ORDER_NOT_FOUND", "message": "Order not found" } }

La correction pratique consiste à faire transiter la forme des erreurs par le même mécanisme de versioning que le corps de la ressource, plutôt que de traiter les réponses d'erreur comme un détail d'implémentation exempté du contrat. Négliger ce point est une des façons les plus courantes dont une "migration v2" passe sans accroc sur le chemin heureux tout en cassant la gestion d'erreur d'un client que personne n'a testé sur ses cas d'échec.

Automatiser la détection des changements cassants en CI

S'appuyer sur la vigilance humaine en revue de code pour repérer un champ renommé dans une réponse JSON ne tient pas dans la durée. La bonne pratique consiste à générer un schéma OpenAPI à partir du code (via les annotations du framework, par exemple springdoc-openapi côté Spring ou @nestjs/swagger côté NestJS), puis à comparer ce schéma à la version précédente à chaque pull request.

# .github/workflows/api-contract-check.yml
name: API contract check
on: [pull_request]
jobs:
  contract-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate current OpenAPI spec
        run: ./scripts/generate-openapi.sh > openapi-current.json
      - name: Diff against main
        run: |
          git show main:openapi.json > openapi-main.json
          npx oasdiff breaking openapi-main.json openapi-current.json --fail-on ERR

oasdiff breaking échoue explicitement la CI si le diff contient un changement classé comme cassant (suppression de champ, changement de type, paramètre devenu obligatoire), ce qui transforme une règle de discipline en contrôle automatique plutôt qu'en espoir que personne ne l'oublie en revue. Un changement volontairement cassant reste possible, mais il doit alors être explicitement assumé (bump de version majeure, documentation de migration), pas glissé discrètement dans un refactor qui semblait anodin.

Quand la solution simple ne suffit pas

Le versioning par en-tête ou par URL répond au "comment coexister", pas au "jusqu'à quand". Si une version doit vivre plusieurs années parce qu'un client enterprise a un cycle de mise à jour contractuel lent, la vraie question devient organisationnelle : qui porte le coût de maintenir deux implémentations divergentes en parallèle, et à partir de quel nombre de versions actives la dette devient-elle plus chère que de négocier une date de fin de support avec ce client. Aucun pattern technique ne résout ça ; c'est un arbitrage produit qu'il faut rendre explicite plutôt que de laisser le nombre de versions actives grandir indéfiniment par défaut.

Versionner une API correctement, c'est accepter que le contrat avec les clients existants est un engagement, pas un détail d'implémentation qu'on peut changer au prochain déploiement. La discipline qui paie sur la durée, c'est moins le choix de stratégie (URI, en-tête, ou autre) que la rigueur à instrumenter qui dépend encore de quoi avant de couper quoi que ce soit.