Blog

JSON Patch: La Méthode Intelligente pour Mettre à Jour les Données de Votre API

INEZA Felin-Michel

INEZA Felin-Michel

1 September 2025

JSON Patch: La Méthode Intelligente pour Mettre à Jour les Données de Votre API

Vous avez bâti une API moderne. Le GET récupère les données, le POST crée de nouvelles ressources – tout va bien jusqu'à présent. Mais lorsqu'il s'agit de mettre à jour des données, les choses se compliquent.

Supposons qu'un utilisateur veuille simplement changer son adresse e-mail. Avez-vous vraiment besoin qu'il renvoie *l'intégralité* de son profil utilisateur ? C'est lourd, inefficace et sujet aux erreurs, surtout avec des connexions lentes ou des mises à jour conflictuelles.

Il existe une meilleure solution : JSON Patch.
Au lieu d'envoyer l'objet entier, vous n'envoyez que les modifications. Imaginez que vous donniez à un tailleur une liste de retouches plutôt que de refaire tout le costume.

Puisque JSON est devenu le langage universel pour les API, JSON Patch offre une solution légère et élégante pour les mises à jour partielles.

Bien sûr, la conception et le test d'API avec JSON Patch nécessitent les bons outils. C'est là qu'Apidog intervient. Il vous permet de créer, tester et valider facilement des requêtes JSON Patch, afin que vous sachiez que vos mises à jour fonctionnent comme prévu avant d'écrire une seule ligne de code. Mieux encore, il est gratuit à télécharger et à expérimenter dès aujourd'hui.

💡
Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et remplace Postman à un prix beaucoup plus abordable !

bouton

Ensuite, détaillons ce qu'est JSON Patch, comment il fonctionne et pourquoi il devrait faire partie de votre prochain projet.

Le Problème : La requête PUT "aveugle"

Pour comprendre pourquoi JSON Patch est si utile, nous devons d'abord comprendre le problème qu'il résout. Traditionnellement, la mise à jour d'une ressource dans une API RESTful se fait avec la méthode HTTP **PUT**.

Une requête **PUT** est censée être idempotente (faire la même requête plusieurs fois a le même effet que de la faire une seule fois) et elle remplace généralement *l'intégralité* de la ressource à l'URL cible par la nouvelle représentation fournie dans le corps de la requête.

Imaginons une ressource de profil utilisateur :

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Maintenant, si John veut simplement changer son adresse e-mail, une requête **PUT** typique ressemblerait à ceci :

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // The changed field
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Voyez-vous le problème ? Nous avons dû renvoyer chaque champ, même si 99 % des données n'ont pas changé. Cette approche présente plusieurs inconvénients :

  1. Augmentation de la bande passante : Nous envoyons beaucoup de données inutiles sur le réseau. Pour les ressources volumineuses, cela peut entraîner une baisse significative des performances, en particulier sur les réseaux mobiles.
  2. Risque accru de conflits : Si un autre processus met à jour le champ **age** pendant que John modifie son **email**, la requête **PUT** de John pourrait accidentellement écraser ce nouvel âge avec l'ancienne valeur qu'il a envoyée.
  3. Complexité pour le client : L'application cliente doit d'abord **GET** l'intégralité de la ressource, modifier le champ spécifique, puis renvoyer le tout avec **PUT**. Il s'agit de plusieurs étapes et cela exige que le client gère l'état entier.

C'est là que la méthode HTTP **PATCH** vient à la rescousse.

La Solution : Introduction de HTTP PATCH et JSON Patch

La méthode HTTP **PATCH** a été introduite pour permettre des modifications partielles d'une ressource. Contrairement à **PUT**, qui remplace l'intégralité de la ressource, **PATCH** applique un ensemble de *modifications* à la ressource.

Mais il y a un hic : la norme HTTP ne définit pas le format de ces "modifications". Vous pourriez inventer le vôtre. Vous pourriez envoyer quelque chose comme :

{ "op": "change_email", "value": "new@example.com" }

Mais cela serait personnalisé, non standard, et d'autres développeurs devraient apprendre votre langage spécifique.

C'est ce vide que JSON Patch comble. JSON Patch (défini dans la RFC 6902) est un format standardisé pour spécifier les modifications à appliquer à un document JSON. Il fournit un langage clair et non ambigu pour décrire exactement comment un document JSON doit être modifié.

Lorsque vous combinez la méthode HTTP **PATCH** avec un corps formaté comme un document JSON Patch, vous disposez d'un moyen puissant et basé sur des standards pour effectuer des mises à jour partielles.

Comment fonctionne JSON Patch : Les bases

Un document JSON Patch est toujours un tableau JSON. Chaque élément du tableau est un objet d'opération. Ces opérations sont appliquées au document cible dans l'ordre, et l'ensemble du patch est atomique, ce qui signifie que si une seule opération échoue, l'ensemble du patch est annulé et le document reste inchangé.

Chaque objet d'opération possède un membre obligatoire **op** (abréviation de "opération") qui spécifie l'action à effectuer. Les opérations les plus courantes sont **add** (ajouter), **remove** (supprimer), **replace** (remplacer), **move** (déplacer) et **copy** (copier).

Reprenons l'exemple précédent de John changeant son e-mail. Avec JSON Patch, la requête devient considérablement plus simple :

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

C'est tout ! Nous envoyons une seule opération : "remplacer la valeur au chemin '/email' par cette nouvelle valeur." La requête est petite, claire et axée sur l'intention. Nous ne touchons aucun autre champ.

Comprendre la propriété path

La propriété **path** est un JSON Pointer (RFC 6901), une chaîne qui utilise une syntaxe basée sur des barres obliques pour naviguer à travers le document JSON jusqu'à la valeur spécifique que vous souhaitez manipuler.

Cette syntaxe est puissante pour naviguer dans les structures JSON imbriquées.

JSON Patch vs JSON Merge Patch

Les développeurs confondent souvent JSON Patch (RFC 6902) avec JSON Merge Patch (RFC 7386). Clarifions.

JSON Patch :

JSON Merge Patch :

En bref :

Les Opérations JSON Patch

Décomposons les opérations les plus courantes avec des exemples. Nous utiliserons le même profil utilisateur comme document cible.

1. L'Opération add

L'opération **add** est utilisée pour insérer une nouvelle valeur dans un objet ou un tableau.

Ajouter une nouvelle propriété à un objet :

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

Cela ajoute un nouveau champ **twitterHandle** à l'objet utilisateur.

Ajouter un élément à un tableau (à un index spécifique) :

Imaginez que l'utilisateur ait un tableau **"hobbies"** : **["reading", "cycling"]**.

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

Cela insère "hiking" à l'index 1, ce qui donne **["reading", "hiking", "cycling"]**. Pour ajouter à la fin du tableau, vous pouvez utiliser **/-** : **{ "op": "add", "path": "/hobbies/-", "value": "hiking" }**.

2. L'Opération remove

L'opération **remove** supprime une valeur à un emplacement spécifié.

Supprimer une propriété d'un objet :

{ "op": "remove", "path": "/age" }

Cela supprime l'intégralité du champ **age** de l'objet utilisateur.

Supprimer un élément d'un tableau :

{ "op": "remove", "path": "/hobbies/0" }

Cela supprime le premier élément (index 0) du tableau **hobbies**.

3. L'Opération replace

L'opération **replace** est essentiellement une combinaison de **remove** et **add** au même chemin. Elle remplace la valeur existante à un emplacement par une nouvelle valeur. Notre exemple d'e-mail était un **replace** classique.

Changer la préférence de thème d'un utilisateur :

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. L'Opération move

L'opération **move** déplace une valeur d'un emplacement à un autre.

Déplacer une valeur d'une propriété à une autre :

{ "op": "move", "from": "/firstName", "path": "/first_name" }

Cela déplacerait la valeur de **firstName** vers une nouvelle propriété appelée **first_name** et supprimerait l'ancienne propriété **firstName**.

5. L'Opération copy

L'opération **copy** copie une valeur d'un emplacement à un autre. La valeur originale reste inchangée.

Créer une sauvegarde d'un paramètre :

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

Cela copie la valeur du thème actuel dans un nouveau champ **backupTheme**.

6. L'Opération test

C'est une fonctionnalité de sécurité. L'opération **test** vérifie qu'une valeur à un emplacement est égale à une valeur spécifiée. Si le test échoue, l'ensemble du patch est annulé. C'est incroyablement utile pour prévenir les conflits (verrouillage optimiste).

S'assurer que personne d'autre n'a changé l'e-mail avant de le mettre à jour :

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Si l'**email** actuel n'est *pas* **"john.old@example.com"** (peut-être qu'un autre processus l'a déjà modifié), l'opération **test** échoue, et le **replace** ne se produit jamais. Cela garantit que votre mise à jour est basée sur le dernier état connu.

Pourquoi utiliser JSON Patch ? Les avantages

  1. Efficacité : L'avantage le plus évident. Vous n'envoyez que les modifications, ce qui réduit considérablement la taille de la charge utile et améliore les performances.
  2. Contrôle de la concurrence : L'opération **test** fournit un mécanisme intégré de verrouillage optimiste, vous aidant à éviter les mises à jour perdues et les conditions de concurrence.
  3. Atomicité : La nature tout-ou-rien d'une application de patch garantit que vos données restent cohérentes. Si la cinquième opération d'un patch de dix opérations échoue, les quatre premières sont annulées.
  4. Clarté et intention : Le corps de la requête décrit clairement l'*intention* du changement ("remplacer l'e-mail", "ajouter un passe-temps") plutôt que de simplement déverser un nouvel état. Cela rend les journaux plus lisibles et le débogage plus facile.
  5. Standardisation : C'est une norme IETF (RFC 6902). D'autres développeurs la reconnaîtront, et de nombreuses bibliothèques et frameworks dans différents langages de programmation ont un support intégré pour l'analyse et l'application des documents JSON Patch.

Pièges et erreurs courants avec JSON Patch

Même si JSON Patch est puissant, les développeurs rencontrent souvent ces problèmes :

Pourquoi les API utilisent JSON Patch

Les API adorent JSON Patch parce que c'est :

Par exemple, l'API de GitHub prend en charge JSON Patch pour modifier efficacement les métadonnées de dépôt.

JSON Patch dans les API REST

Dans les API RESTful, JSON Patch est souvent utilisé avec la méthode HTTP PATCH.

PATCH vs PUT :

Avec JSON Patch, le Content-Type est :

application/json-patch+json

Cela indique au serveur que le corps contient un document JSON Patch.

JSON Patch dans GraphQL et autres protocoles

Bien que JSON Patch soit principalement utilisé dans les API REST, il est également pertinent dans :

Comment JSON Patch améliore l'efficacité

Imaginez une application mobile synchronisant les profils utilisateur. Au lieu de re-télécharger un fichier JSON de 2 Mo pour chaque petite mise à jour, l'application peut simplement envoyer une petite requête de patch.

Cela signifie :

Défis et considérations

JSON Patch est puissant, mais il n'est pas sans ses complexités.

  1. Implémentation complexe côté serveur : Appliquer un patch correctement côté serveur est plus complexe que d'accepter simplement un nouvel objet JSON. Vous devez valider chaque opération, gérer les pointeurs vers des chemins inexistants de manière appropriée et vous assurer que toute la séquence est appliquée atomiquement. Heureusement, la plupart des frameworks web modernes disposent de bibliothèques pour gérer cela (par exemple, **json-patch** pour Node.js, **jsonpatch** pour Python, **JsonPatchDocument** dans .NET).
  2. Potentiel d'erreurs : Un document de patch mal formé ou un pointeur invalide (par exemple, tenter de **replace** un champ qui n'existe pas) entraînera une erreur. Votre API doit gérer ces erreurs avec élégance et renvoyer des messages d'erreur clairs (généralement un **422 Unprocessable Entity** ou **400 Bad Request**).
  3. Pas une solution miracle : Pour des ressources très simples, un **PUT** pourrait toujours être plus simple. JSON Patch brille lorsque vos ressources sont volumineuses ou lorsque vous avez besoin de prendre en charge des mises à jour complexes et conditionnelles.

Tester un point de terminaison JSON Patch avec Apidog

Tester JSON Patch manuellement peut être frustrant. C'est là qu'un outil API sophistiqué devient inestimable. Apidog, une plateforme de développement API tout-en-un, peut être d'une grande aide ici :

bouton

Exemple de flux de travail dans Apidog :

  1. Créez une nouvelle requête.
  2. Définissez la méthode sur PATCH.
  3. Ajoutez Content-Type: application/json-patch+json.
  4. Saisissez votre tableau JSON Patch.
  5. Envoyez et vérifiez les résultats instantanément.

En utilisant Apidog, vous passez de l'incertitude quant à la correction de votre patch à la certitude qu'il est bien construit, vous permettant d'implémenter et de consommer des API JSON Patch en toute confiance et de commencer à tester JSON Patch comme un pro.

Meilleures pratiques JSON Patch

Pour utiliser JSON Patch efficacement :

  1. Validez vos documents JSON Patch avant de les envoyer.
  2. Utilisez les opérations de test lorsque la cohérence est importante.
  3. Gardez les patchs petits pour plus d'efficacité.
  4. Documentez clairement votre API lorsque vous utilisez JSON Patch.
  5. Utilisez des outils comme Apidog pour simplifier les tests.

Conclusion : Adopter une norme API plus efficace

Alors, qu'est-ce que JSON Patch ?

C'est un moyen standardisé de décrire les modifications apportées aux documents JSON en utilisant des opérations comme l'ajout, la suppression et le remplacement. Au lieu d'envoyer des objets complets, vous pouvez n'envoyer que les modifications, rendant vos API plus efficaces, fiables et flexibles.

JSON Patch transforme la façon dont nous concevons la mise à jour des données via les API. Il nous fait passer de l'instrument grossier du remplacement de document complet à la précision des modifications chirurgicales. En adoptant cette norme, nous construisons des API plus efficaces, moins sujettes aux conflits et plus claires dans leur intention.

Bien que cela demande un peu plus de réflexion en amont côté serveur, les avantages pour les applications clientes et les performances réseau sont substantiels. La prochaine fois que vous concevrez un point de terminaison de mise à jour, résistez au **PUT** par défaut et demandez-vous : "Cela pourrait-il être un travail pour **PATCH** ?"

Pour les développeurs, comprendre JSON Patch est essentiel pour travailler avec les API modernes, en particulier lors de la gestion des mises à jour partielles. Et avec des outils comme Apidog, vous pouvez tester, valider et déboguer les requêtes JSON Patch en toute simplicité.

bouton

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger