Formats et contrats d’échange
JSON Merge Patch voyage : champs retirés et listes remplacées
Une petite correction peut retirer une consigne ou remplacer tous les équipements d’une offre. Préparez l’état initial, le changement demandé et le résultat attendu, puis vérifiez la portée du format de mise à jour utilisé.
Le repère documentaire et sa portée
Dans un objet Merge Patch, null retire un membre ; une liste remplace la liste entière. Un patch non objet remplace toute la cible. Transformation des valeurs JSON selon RFC 7396 ; ce mécanisme doit être explicitement supporté par l’API avant tout usage.
Confirmer le format avant d’interpréter le changement
Demandez le mécanisme de l’opération : document complet, format propre au fournisseur, JSON Merge Patch ou autre contrat. Une méthode HTTP PATCH ne suffit pas à établir le sens de son corps. Notez l’endpoint et le type de contenu attendu. Le guide et le simulateur ne prouvent pas qu’une API voyage accepte ce format.
Comparer les trois documents
Conservez la cible fictive, le patch demandé et le résultat attendu par l’équipe métier. Faites examiner les champs qui restent et ceux qui disparaissent. Une correction de description ne doit pas supprimer une information encore utile par accident. Le test doit montrer les différences lisibles, puis expliquer lesquelles sont voulues.
Préparer un remplacement de liste
Scénario fictif : une fiche contient trois équipements et le changement n’en mentionne plus qu’un. Demandez si le résultat attendu est une liste complète ou l’ajout d’un élément. Faites rejouer le cas avant de publier. Si l’application doit agir sur un élément identifié, choisissez l’opération documentée qui répond à ce besoin au lieu de supposer un comportement d’ajout.
Traiter les suppressions comme des décisions
Un champ retiré peut représenter une ancienne consigne, un prix ou un lien. Désignez qui peut demander ce retrait et qui doit relire ses conséquences dans les pages et documents. Si une donnée inconnue doit rester explicitement représentée par null, examinez un format adapté à cet usage. Gardez la suppression séparée d’une absence de nouvelle information.
Faire approuver le résultat avant application
Utilisez des exemples fictifs dans le simulateur local, puis conservez le résultat voulu et les limites. L’essai ne transmet aucune opération au fournisseur. Une application réelle exige les droits, la version courante, les contrôles métier et la possibilité de retrouver l’état avant changement. Le document final doit permettre à un collègue de relire ce qui sera retiré ou remplacé.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- IETF : RFC 7396, JSON Merge Patch — Transformation des valeurs JSON selon RFC 7396 ; ce mécanisme doit être explicitement supporté par l’API avant tout usage. (consultée le )
Questions fréquentes
Questions utiles avant de décider
PATCH signifie-t-il automatiquement Merge Patch ?
Le format de corps doit être établi par l’API. La méthode HTTP ne suffit pas à choisir les règles de transformation.
Le simulateur modifie-t-il un catalogue fournisseur ?
Il calcule un résultat dans le navigateur à partir des deux textes fournis. Il n’envoie pas d’opération à une API.
Comment montrer une correction sans retirer les autres équipements ?
Préparez le résultat complet voulu et utilisez l’opération documentée pour cet usage. Faites relire la liste avant toute application.
