Exploiter toute la puissance de JSON Patch

• JSON Patch est un format standard défini dans la RFC 6902, qui décrit une méthode pour modifier des documents JSON
  • Il offre un moyen simple et efficace de mettre à jour partiellement des ressources via HTTP
  • Alors que les méthodes PUT et POST imposaient l’envoi de l’ensemble des données, la méthode PATCH autorise les mises à jour partielles
• JSON Patch fournit une représentation claire et concise des changements à apporter à un document JSON, ce qui réduit la bande passante utilisée et améliore les performances des applications web

Fonctionnement de JSON Patch

• JSON Patch fonctionne comme une série d’opérations atomiques sur un document JSON.
• Chaque opération inclut un champ op et un champ path, qui permettent d’exécuter l’action à un emplacement précis du document.
• Par exemple, l’opération add ajoute un nouveau champ, et l’opération replace remplace un champ existant.

JSON Pointer

• JSON Patch utilise JSON Pointer pour identifier une partie précise du document.
• JSON Pointer est une chaîne de jetons séparés par des slashs (/), qui identifie la structure hiérarchique du document.
• Par exemple, /user/name identifie le champ name dans l’objet user.

Avantages et inconvénients de JSON Patch

Avantages

1. Précision : permet de modifier exactement un élément donné dans des structures complexes.
2. Efficacité : seules les modifications sont transmises, ce qui minimise le volume de données et la latence.
3. Atomicité : en cas d’échec, l’ensemble des opérations peut être annulé.
4. Idempotence : permet des tentatives répétées en toute sécurité.
5. Opérations complexes : permet de déplacer ou de copier des éléments.
6. Validation : l’API peut valider les patchs entrants afin de réduire les requêtes invalides.
7. Basé sur un standard : s’intègre facilement avec différents clients et serveurs.
8. Contrôle d’accès au niveau des champs : permet de restreindre les modifications de manière fine.
9. Traitement par lot : permet de regrouper plusieurs changements dans une seule requête.

Inconvénients

1. Complexité : peut être difficile à utiliser avec des structures JSON complexes.
2. Coût de maintenance : les chemins peuvent devenir invalides à mesure que l’API évolue.
3. Débogage difficile : le suivi devient plus compliqué lorsque plusieurs opérations sont regroupées.
4. Préservation de l’ordre des objets : les opérations de déplacement ne garantissent pas l’ordre des objets.
5. Problèmes de sécurité : une mauvaise gestion des requêtes peut introduire des vulnérabilités.

Exemples d’opérations JSON Patch

• Add : ajoute un nouveau champ.
• Remove : supprime un champ existant.
• Replace : remplace un champ existant par une nouvelle valeur.
• Move : déplace un élément vers un autre emplacement.
• Copy : copie un élément vers un autre emplacement.
• Test : vérifie si une valeur est définie à un chemin donné.

JSON Patch dans les outils et bibliothèques

• Il existe des bibliothèques prenant en charge JSON Patch dans de nombreux langages de programmation : fast-json-patch, python-json-patch, JsonPatch library in .NET, etc.
• Un excellent outil pour apprendre JSON Patch est jsonpatch.me, un service en ligne gratuit permettant d’exécuter des commandes JSON Patch. Une API est également disponible

Le récapitulatif de GN⁺

• JSON Patch est un outil puissant pour effectuer efficacement des mises à jour partielles de documents JSON.
• Même s’il peut être difficile à utiliser avec des structures JSON complexes, divers outils et bibliothèques permettent de surmonter ces difficultés.
• JSON Patch est utile pour réduire le volume de données transférées et améliorer les performances des applications web.
• Des alternatives comme JSON Merge Patch peuvent aussi être envisagées, et l’usage de JSON Patch peut améliorer l’efficacité du développement d’API.

[GN⁺]

Commentaires sur Hacker News

• JSON Patch est conçu pour pouvoir modifier n’importe quel document JSON, ce qui le rend complexe. Si l’on restreint légèrement l’ensemble de données, on peut appliquer des patchs aux documents de façon bien plus simple. Par exemple, dans Firebase, on ne peut pas stocker de valeurs null, et définir une valeur à null signifie la supprimer. Ce type de contrainte simple permet d’implémenter facilement PATCH. C’est une excellente propriété d’une API : à part le fait que « null signifie suppression », il n’y a rien de nouveau à apprendre.

• Utiliser / comme séparateur pour JSON est un choix étrange. Comme JSON est un sous-ensemble de JS, je m’attendais à . comme séparateur. En voyant /, on dirait une spécification écrite par des gens du back-end, qui essaient peut-être de transformer les chemins en URL pour résoudre l’ambiguïté entre chemins relatifs et absolus.

• Je pense que le chemin devrait être un tableau plutôt qu’une chaîne. Sinon, il faut échapper / dans les clés et analyser la chaîne de chemin. Cela empêche de traiter des documents JSON arbitraires.

• J’ai déjà utilisé JSON Patch comme un hack pour résoudre rapidement un problème imprévu. J’avais construit une interface web pour permettre à des sous-traitants à l’étranger d’annoter des données textuelles au niveau des mots. Les données devaient être annotées par petits blocs, mais elles se sont retrouvées attribuées sous forme de documents entiers, ce qui empêchait l’enregistrement des annotations. J’ai découvert JSON Patch et modifié le code d’upload pour qu’il n’utilise plus que des patchs.

• Il faudrait une syntaxe standard qui permette, dans le mécanisme de désignation des chemins de JSON Patch, de sélectionner les éléments d’un tableau par une paire clé-valeur d’identification plutôt que par index. C’est particulièrement important lorsqu’on ajoute des éléments ou qu’on analyse les différences avec une ancienne version d’éléments JSON.

• L’un des points forts de JSON Patch est son idempotence. Les opérations JSON Patch peuvent être retentées en toute sécurité sans effets de bord involontaires. En revanche, j’ai été surpris qu’on ne puisse pas ajouter d’éléments à un tableau.

• Cela fonctionne de manière similaire aux requêtes de mise à jour de MongoDB. Je me demande s’il est possible d’utiliser ce langage de mise à jour sur des fichiers locaux sans exécuter tout MongoDB.

• Il faudrait une comparaison entre JSONDiffpatch et JSON Patch. JSONDiffpatch fonctionne bien dans le navigateur ainsi que sur Node / Cloudflare Workers, entre autres.

• J’ai eu du mal à convaincre des partenaires externes d’apprendre JSON Patch. Je l’ai utilisé dans une API destinée aux clients, et il a fallu beaucoup d’efforts pour que les utilisateurs le comprennent et l’adoptent.

• La spécification JSON Pointer donne une impression très « URL-y », ce qui laisse penser qu’on pourrait éviter une syntaxe méta-JSON. test et copy sont propres à la spécification JSON Patch, et il est aussi possible d’effectuer plusieurs modifications en une seule fois, sous forme de « transaction ».