Introduction à JSON Merge Patch

Introduction à JSON Merge Patch

C’est quoi? A quoi ça sert?

JSON Merge Patch est un format de données qui permet de décrire les modifications à apporter à un document JSON.

Ce format peut être utilisé dans les API REST afin de gérer les modifications partielles de ressources, via la méthode HTTP PATCH.

Le format JSON Merge Patch est lui-même un document JSON! En gros, ce JSON ne contient que les modifications à apporter.

L’intérêt de JSON Merge Patch

Quand on veut mettre à jour une ressource dans une API REST, on utilise la méthode PUT.

La méthode PUT permet de faire une mise à jour complète de la ressource, et cela pose plusieurs problématiques:

  • Il faut avoir l’ensemble de la ressource pour la mettre à jour.
  • Quand la ressource est volumineuse, la mise à jour devient vite gourmande en ressource.

C’est là l’intérêt de la méthode PATCH, et de l’utilisation de JSON Merge PATCH. Cela donne la possibilité de mettre à jour une ressource partiellement!

Et concrètement?

Modifier un attribut

Prenons comme exemple la ressource /personnes/cyril

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"]
}

Si on veut changer le travail de cette personne, avec la méthode PUT, il faut renvoyer complètement la ressource:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"]
}

Maintenant avec JSON Merge Patch, on ne met que ce qui est à mettre à jour:

{
	"job": "Project Manager"
}

Et voilà, ce format est assez simple et intuitif!

Ajouter un attribut

Maintenant, si on veut ajouter un attribut, il suffit de le mettre:

{
	"birthday": "1982-10-14"
}

Nous obtenons en résultat:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"],
	"birthday": "1982-10-14"
}

Supprimer un attribut

Pour supprimer un attribut, il suffit de l’indiquer avec une valeur null:

{
	"birthday": null
}

Nous obtenons en résultat:

{
	"firstname": "Cyril",
	"job": "
Project Manager",
	"hobbies": ["Cooking"]
}

API REST

Ce format est donc à utiliser avec la méthode HTTP PATCH.

Son media type est:

application/json+merge-patch

Les limitations

JSON Merge Patch est vraiment simple d’utilisation, et sa prise en main est rapide. Malheureusement, ce format présente plusieurs limitations dont certaines sont assez gênantes.

Valeur null

Comme on a vu dans la section « Supprimer un attribut », la valeur null sert à supprimer un noeud. Il est ainsi impossible d’affecter la valeur null!

Fonctionnellement, ce point ne semble pas forcément très gênant.

Mise à jour de tableau

De mon point de vue, c’est le point le plus embêtant avec ce format . En effet, les tableaux ne peuvent pas être mis à jour partiellement!

Si je veux ajouter un loisir, je dois envoyer complètement le tableau:

{
	"hobbies": ["Cooking", "Running"]
}

JSON Merge Patch ne permet de mettre à jour partiellement que les objets. Tout ce qui n’est pas un objet sera remplacé totalement.

Code PHP permettant de gérer JSON Merge Patch

Gérer la mise à jour partielle via JSON Merge Patch est assez simple en PHP, voici un exemple de code:

function JSONMergePatch($target, $patch) {
	if (is_object($patch)) {
		if (!is_object($target)) {
			$target = new \stdclass();
		}
		foreach($patch as $name => $value) {
			if ($value === null) {
				// On supprime le noeud quand on reçoit une valeur null
				if (property_exists($target, $name)) {
					unset($target->$name);
				}
			} else {
				if (!isset($target->$name)) {
					$target->$name = null;
				}
				// Appel récursif pour gérer la sous-arborescence
				$target->$name = JSONMergePatch($target->$name, $value);
			}
		}
		return $target;
	} else {
		// Ce n'est pas un objet, on remplace le noeud
		return $patch;
	}
}	

JSON Merge Path vs JSON Patch

JSON Merge Patch n’est pas le seul format disponible pour gérer la mise à jour partielles dans les API.

L’un de ses concurrents est JSON Patch, celui-ci est moins intuitif, mais a l’avantage de ne pas avoir les limitations de JSON Merge Patch.

Conclusion

Pour résumer JSON Merge Patch est intuitif et facile d’implémentation. Mais malheureusement il est assez limité, et perd de sa pertinence dès que l’on gère des tableaux.

Pour plus d’informations, voir la RFC.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *