Une API qui fonctionne bien techniquement mais qui casse ses clients à chaque mise en production n'est pas une API fiable, quelle que soit la qualité du code derrière. Le problème n'est presque jamais le endpoint lui-même : c'est l'absence de contrat explicite sur ce qui peut changer sans préavis et ce qui ne peut pas. Ce billet pose des règles concrètes pour faire évoluer une API REST (ou GraphQL, dans une moindre mesure) sans transformer chaque déploiement en incident potentiel chez les consommateurs.

Le problème : la compatibilité n'est jamais écrite nulle part

Dans la majorité des projets, il n'existe aucune définition partagée de ce qu'est un "breaking change". Un développeur ajoute un champ obligatoire dans le payload d'une requête, renomme une clé JSON pour la rendre plus claire, ou change le format d'une date de "2025-12-01" à un timestamp Unix - et considère que ce sont des détails d'implémentation. Côté client, ce sont des pannes en production.

Le symptôme typique : un correctif publié un vendredi casse silencieusement un client mobile qui n'a pas encore été mis à jour, parce que le champ status qui valait auparavant "actif" vaut maintenant "ACTIVE". Personne n'a changé de version d'API. Personne n'a prévenu personne.

Pourquoi ça arrive : l'API comme interface implicite

Une API REST est un contrat, au même titre qu'une signature de fonction publique dans une bibliothèque. Le problème est que ce contrat est rarement formalisé au-delà d'un schéma OpenAPI généré après coup, qui documente l'état actuel sans jamais s'engager sur sa stabilité future.

Trois catégories de changements sont systématiquement sous-estimées :

  • Changements de structure : renommer un champ, changer son type (string vers number), passer d'un objet à un tableau.
  • Changements de sémantique : le champ garde son nom et son type, mais sa signification change (un total qui incluait la TVA n'en inclut soudain plus).
  • Changements de comportement : un code HTTP différent pour le même cas d'erreur, un ordre de tri qui change, une pagination qui devient cursor-based au lieu d'offset-based.

Les deux dernières catégories sont les plus dangereuses parce qu'elles ne cassent rien au niveau du typage ou de la validation de schéma : tout continue de "marcher", mais le client prend de mauvaises décisions avec des données correctement formées.

Diagnostiquer : tracer qui consomme quoi

Avant de changer quoi que ce soit, il faut savoir qui consomme l'API et comment. Sans cette visibilité, toute modification est un pari.

// Middleware Express pour journaliser l'usage réel par client
function trackApiUsage(req, res, next) {
  const clientId = req.headers['x-client-id'] ?? 'unknown';
  const apiVersion = req.headers['x-api-version'] ?? 'unversioned';

  metrics.increment('api.request', {
    route: req.route?.path ?? req.path,
    method: req.method,
    clientId,
    apiVersion,
  });

  next();
}

Avec ces métriques agrégées sur quelques semaines, on peut répondre à des questions concrètes : quels clients utilisent encore la v1, quels endpoints sont réellement appelés en production (beaucoup le sont rarement), et quels champs de réponse sont effectivement lus côté client (difficile à savoir côté serveur, mais un grep côté client mobile ou web donne une bonne indication si on a accès au code consommateur).

La correction : des règles de compatibilité explicites

Versionner au niveau du contrat, pas du code

Le versionnement dans l'URL (/v1/orders, /v2/orders) ou dans un en-tête (Accept: application/vnd.myapi.v2+json) sert à isoler les breaking changes, pas à versionner chaque micro-évolution. La règle de base reste celle popularisée par Stripe et la plupart des API matures : à l'intérieur d'une version majeure, seuls les changements additifs sont autorisés.

Changements non cassants (safe à l'intérieur d'une version) :

  • ajouter un nouveau champ optionnel dans une réponse,
  • ajouter un nouveau endpoint,
  • ajouter une valeur possible à une énumération, si les clients sont contractuellement tenus de gérer les valeurs inconnues avec une valeur par défaut.

Changements cassants (nécessitent une nouvelle version ou une période de dépréciation) :

  • supprimer ou renommer un champ,
  • rendre obligatoire un champ qui était optionnel,
  • changer le type ou le format d'un champ existant,
  • changer le code de statut HTTP d'une réponse existante.

Formaliser le contrat avec un schéma versionné et testé

Un schéma OpenAPI ou un schéma JSON n'a de valeur que s'il est testé en CI contre les réponses réelles, pas seulement généré comme documentation statique.

# openapi.yaml - extrait, avec champ additif et champ déprécié explicite
components:
  schemas:
    Order:
      type: object
      required: [id, status, totalAmount]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, confirmed, shipped, cancelled]
        totalAmount:
          type: number
          description: "Montant total incluant la TVA, en centimes."
        legacyTotal:
          type: number
          deprecated: true
          description: "Déprécié depuis v2.3, supprimé en v3. Utiliser totalAmount."
// Test de contrat : vérifie qu'aucun champ requis n'a disparu
// et que les champs dépréciés sont toujours présents jusqu'à la date de retrait
import { validateAgainstSchema } from './schema-validator.js';
import ordersResponseV2 from './fixtures/orders-v2-response.json';

test('la réponse /v2/orders respecte le contrat publié', () => {
  const result = validateAgainstSchema(ordersResponseV2, 'Order');
  expect(result.missingRequiredFields).toEqual([]);
  expect(result.deprecatedFieldsRemoved).toEqual([]);
});

Dépréciation progressive, jamais de suppression sèche

Le cycle sain pour retirer un champ ou un endpoint : annoncer la dépréciation (en-tête Deprecation et Sunset selon la RFC 8594, documentation, email aux intégrateurs connus), laisser une fenêtre réaliste (plusieurs semaines à plusieurs mois selon la base de clients), surveiller via les métriques d'usage que le trafic sur l'ancien champ tombe à zéro, puis seulement retirer.

app.get('/v2/orders/:id', (req, res) => {
  const order = getOrder(req.params.id);

  res.set('Deprecation', 'true');
  res.set('Sunset', 'Wed, 01 Apr 2026 00:00:00 GMT');
  res.set('Link', '</docs/migration/orders-v3>; rel="deprecation"');

  res.json({
    ...order,
    legacyTotal: order.totalAmount, // champ dupliqué pendant la transition
  });
});

Les compromis

Maintenir plusieurs versions en parallèle a un coût réel : duplication de logique, tests multipliés, confusion pour les nouveaux arrivants dans l'équipe sur quelle version modifier. La tentation de "nettoyer" en cassant tout d'un coup est forte, mais elle déplace le coût sur les clients, qui ne contrôlent pas toujours leur calendrier de mise à jour (applications mobiles avec des versions encore installées chez des utilisateurs qui ne mettent jamais à jour, intégrations tierces gérées par d'autres équipes).

Une alternative pragmatique est la compatibilité par transformation à la frontière : garder un seul modèle de données interne, et adapter la forme exposée selon la version demandée dans une couche de sérialisation dédiée, plutôt que de dupliquer la logique métier.

Quand la version "simple" ne suffit pas

Verser dans le versionnement de version à chaque changement mineur produit l'effet inverse de celui recherché : les clients n'ont plus aucune garantie de stabilité et migrent en permanence. Si une API change si souvent que le versionnement par URL devient ingérable, le vrai problème est probablement un manque de stabilisation du modèle de données en amont, pas un manque d'outillage de versionnement.

Pour les API internes à fort couplage (microservices d'une même équipe), le versionnement strict est parfois un coût disproportionné : un contrat partagé avec des tests de compatibilité consommateur (contract testing, à la Pact) peut suffire sans multiplier les versions d'URL.

Le point à retenir : la rétrocompatibilité n'est pas une contrainte qu'on subit après coup, c'est une discipline qu'on code - schéma versionné, tests de contrat en CI, en-têtes de dépréciation standard. Sans ça, chaque déploiement redevient un pari sur ce que les clients ne remarqueront pas.