Une API n’est pas compatible simplement parce qu’elle conserve la même route ou la même version. Ses consommateurs dépendent aussi de la forme des données, des règles de validation, des valeurs par défaut et du comportement en cas d’erreur. Si différents clients se mettent à jour à des rythmes différents, un changement qui semble mineur à la personne chargée de la maintenance du serveur peut interrompre une application mobile, une intégration tierce ou un processus interne.
Une politique de compatibilité des données dans les API PHP transforme ce risque en décisions explicites : quels changements sont acceptés, comment les déployer et quels tests doivent être réussis avant de retirer un contrat. Il n’existe pas de règle universelle qui rende n’importe quel changement compatible ; il faut tenir compte de la façon dont chaque consommateur lit et envoie les données.
Le contrat comprend les données, la validation et le comportement
Le contrat d’une API couvre davantage que le schéma documenté. Il comprend les champs et leurs types, la possibilité de les omettre ou de leur attribuer la valeur nulle, l’interprétation des dates et des montants, les valeurs acceptées dans une requête, le format des erreurs et les garanties relatives à la réponse. Il comprend aussi des règles observables, comme l’ordre d’une collection lorsque les clients en dépendent, ou la stabilité d’un identifiant.
En PHP, les objets de transfert, les validateurs et les sérialiseurs matérialisent souvent certaines parties de ce contrat. Examiner uniquement le contrôleur peut laisser passer des changements incompatibles cachés dans une règle de validation, une ressource de réponse ou un mappage entre le modèle et l’API. Il est préférable de documenter le contrat à partir de ce que le client observe réellement, et non de la structure interne des classes ou des tables.
Classer les changements en fonction du consommateur
La classification est un outil d’évaluation, pas une garantie automatique. Un changement additif permet généralement aux clients qui ignorent les champs inconnus de continuer à fonctionner, mais peut interrompre les consommateurs qui convertissent la réponse en une structure stricte ou la valident par rapport à un schéma fermé. De même, un nouveau champ facultatif dans une requête peut être sans conséquence pour les anciens clients, alors que le rendre obligatoire ne l’est pas.
- Généralement additifs : ajouter un champ facultatif à une requête ou à une réponse, ou ajouter une valeur à une collection, à condition que les consommateurs tolèrent ces éléments.
- Potentiellement incompatibles : supprimer ou renommer un champ, en modifier le type, rendre obligatoire un champ facultatif, modifier le format d’une erreur ou changer la signification d’une valeur existante.
- Dépendants du contexte : modifier l’ordre, la précision numérique, le fuseau horaire, la sémantique d’un état ou les critères de pagination. Même si le schéma ne change pas, le résultat peut être différent pour le client.
Avant d’approuver un changement, identifiez les consommateurs et examinez la façon dont ils traitent la donnée. Un champ inconnu peut être ignoré, déclencher une erreur de validation ou être transmis à une logique qui ne l’attend pas. Ne supposez pas que tous les langages, bibliothèques ou versions de clients réagissent de la même manière.
Faire évoluer les requêtes et les réponses avec prudence
Dans les réponses, l’ajout d’un champ est plus sûr si l’on tient compte du fait que des clients stricts peuvent rejeter les propriétés supplémentaires. Si la signification ou le type d’un champ change, ne le réutilisez pas silencieusement. Introduisez un nouveau champ doté d’une sémantique claire, documentez son lien avec l’ancien et maintenez les deux pendant une période de transition définie.
Dans les requêtes, il est essentiel de distinguer une valeur absente, nulle et vide. En PHP, une validation qui traite l’absence d’une clé de la même façon que sa valeur null peut effacer des données ou appliquer des valeurs par défaut inattendues. Définissez la signification de chaque cas et testez les nouveaux clients comme les anciens. Pour un nouveau champ, envisagez d’accepter d’abord son absence et de lui attribuer un comportement compatible, plutôt que de l’exiger dès le premier déploiement.
Le versionnement des routes n’est pas la seule option. Il est possible de faire évoluer un contrat en conservant la route si les changements sont compatibles, ou de publier une nouvelle version lorsqu’ils ne le sont pas et que la coexistence est pertinente sur le plan opérationnel. Dans les deux cas, documentez la politique de prise en charge : une étiquette de version, à elle seule, n’indique pas combien de temps un contrat restera disponible.
Déployer la base de données et l’API par étapes
Un déploiement sûr sépare les changements de stockage de l’activation du nouveau comportement. Une séquence courante consiste à étendre le schéma, à déployer du code capable de fonctionner avec l’ancienne et la nouvelle structure, à migrer les données si nécessaire, puis à activer la nouvelle lecture ou écriture. La suppression des anciennes colonnes ou des anciens chemins intervient ensuite, lorsqu’il existe des preuves suffisantes qu’ils ne sont plus nécessaires.
Cette approche d’expansion et de contraction évite qu’une version de l’application attende une colonne qui n’existe pas encore ou qu’un nouveau déploiement cesse de fonctionner avec d’anciens processus. Dans les systèmes comportant plusieurs instances ou des travailleurs en arrière-plan, tenez compte du fait que différentes versions du code peuvent coexister pendant le déploiement. Les migrations doivent être compatibles avec cette coexistence et prévoir une stratégie de récupération en cas d’échec d’une étape.
L’activation progressive — par exemple, activer une fonctionnalité pour une partie contrôlée des consommateurs — peut limiter l’impact, mais elle ne constitue pas une divulgation publique et ne remplace pas la compatibilité. Utilisez des mécanismes d’activation lorsqu’ils permettent d’observer et d’annuler le comportement ; définissez à l’avance les conditions qui interrompent l’extension.
Mesurer l’utilisation sans enregistrer de données sensibles
Pour savoir quels consommateurs utilisent encore un contrat, la télémétrie doit identifier la version ou la fonctionnalité concernée sans stocker de corps de requête ou de réponse contenant des informations personnelles, des identifiants d’authentification ou des données commerciales. Enregistrez des signaux minimaux, comme la route, la version du client déclarée, le résultat et la date ; limitez l’accès et la durée de conservation en fonction des besoins opérationnels et des obligations applicables.
Le signal doit être utile à la prise de décision. Distinguez les requêtes d’utilisateurs réels des tests, des nouvelles tentatives ou du trafic automatisé ; observez également les erreurs, la latence et l’évolution du volume. S’il n’existe pas d’identifiant client fiable, ne déduisez pas son identité à partir de données sensibles. Gardez à l’esprit que les proxys, les clés partagées et les clients qui n’envoient pas de version peuvent créer des zones sans visibilité.
Retirer un contrat selon des critères vérifiables
Ne retirez pas une version simplement parce qu’une échéance annoncée est passée. Définissez des signaux et des seuils adaptés au risque : absence durable de trafic identifiable, migration confirmée des intégrations connues, stabilité de la version qui lui succède et procédure d’assistance pour les exceptions. Si un trafic inconnu persiste, enquêtez avant d’interpréter l’absence d’identification comme une absence d’utilisation.
Communiquez à l’avance les changements, les personnes concernées, la solution de remplacement, les dates prévues et la manière de tester la migration. Maintenez ces informations dans une documentation accessible aux équipes consommatrices et mettez en place un canal pour signaler les incompatibilités. Si l’impact ne peut pas être annulé rapidement, envisagez une transition plus longue ou la coexistence temporaire des contrats.
Liste de contrôle avant la publication
- Les champs, types, possibilités de valeur nulle, valeurs par défaut et erreurs concernés ont-ils été documentés ?
- Le comportement des clients tolérants et stricts face aux champs nouveaux ou absents a-t-il été vérifié ?
- Les tests de contrat couvrent-ils les consommateurs connus et les cas limites de validation ?
- La migration de la base de données permet-elle la coexistence avec les anciennes versions de l’application ?
- Dispose-t-on de métriques suffisantes pour détecter les erreurs et l’utilisation du contrat sans capturer de données sensibles ?
- Les responsables, la communication, les critères d’annulation et les conditions de retrait de l’ancien contrat ont-ils été définis ?
Une politique utile ne promet pas qu’aucun changement n’interrompra aucun client. Elle explicite les hypothèses, limite les surprises et permet d’agir sur la base de faits. Réexaminez ces décisions à chaque changement de contrat, en particulier lorsque l’API a des consommateurs externes dont l’équipe ne maîtrise pas le cycle de mise à jour.
