Introduction à JSON Patch

Introduction à JSON Patch

Lors d’un précédent article, j’avais présenté JSON Merge Patch. JSON Patch est tout simplement une alternative!

C’est un format qui permet de gérer la modification partielle de document JSON. C’est utilisé dans les API REST, via la méthode HTTP PATCH. Son type mime (Type de média) est application/json-patch+json

Format JSON Patch

Un document JSON patch est simplement un fichier JSON contenant un tableau d’opérations de patch.

Voici un petit exemple pour avoir un aperçu de ce format:

[
	{ "op": "add", "path": "/hobbies/1", "value": "Sport" },
	{ "op": "remove", "path": "/job" }
]

Dans cet exemple, on retrouve deux opérations:

  • Un ajout de la valeur Sport.
  • La suppression de la valeur job

Les opérations

Liste des opérations possibles:

  • add: Ajoute un attribut à un objet ou ajoute un élément à un tableau Pour les tableaux:
    • L’élément est inséré avant l’indice indiqué.
    • Le caractère « – » permet d’insérer une valeur à la fin du tableau.
  • remove: Supprime une valeur.
  • replace: Remplace une valeur.
  • move: Déplace une valeur.
  • copy: Copie une valeur.
  • test: Vérifie qu’une valeur est bien définie. Sinon la mise à jour est mise en échec.

Les opérations sont appliquées dans l’ordre. Et dès que l’une d’elles échoue, l’opération dans son ensemble est en échec.

JSON Pointer

On retrouve ce format dans l’attribut « path » dans les opérations.

Le pointeur JSON (IETF RFC 6901) permet d’identifier une valeur spécifique dans un document JSON.

Cela se rapproche de JSONPath sauf que celui-ci permet de faire des recherches, et de retourner plusieurs valeurs.

Ce format est assez simple:

  • Le path commence par un slash
  • Chaque segment est séparé par un slash
  • Chaque segment est soit le nom d’un attribut (pour les objets) soit un indice (pour les tableaux)

Prenons comme exemple la ressource /personnes/cyril

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "chanel"
		}
	]
}

L’attribut name a comme path /pets/0/name.

Quelques exemples

Ajouter un attribut

Ajoutons un attribut eye à notre ressource ressource /personnes/cyril:

[
	{ "op": "add", "path": "/eye", "value": "Green" }
]

Nous obtenons:

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Ajouter un élément dans un tableau

Maintenant, nous allons ajouter un animal de compagnie:

[
	{ "op": "add", "path": "/pets/0", "value": {"type": "cat", "name": "Horu"} }
]

Nous obtenons:

{
	"firstname": "Cyril",
	"job": "Developer",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Modifier une valeur

Nous allons changer le job:

[
	{ "op": "add", "path": "/job", "value": "Project Manager" }
]

Nous obtenons:

{
	"firstname": "Cyril",
	"job": "Project Manager",
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Valeur null

Il n’y a pas de cas particulier pour la valeur null, il est possible d’affecter cette valeur à un attribut.

Nous allons affecter la valeur null à l’attribut job:

[
	{ "op": "add", "path": "/job", "value": null }
]

Nous obtenons:

{
	"firstname": "Cyril",
	"job": null,
	"hobbies": ["cooking"],
	"pets" : [
		{
			"type": "cat",
			"name": "Horu"
		}
,
		{
			"type": "cat",
			"name": "chanel"
		}
	],
	"eye": "Green",
}

Les limitations / Inconvénients

Contrairement à JSON Merge Patch, ce format n’a pas de limitation fonctionnelle. Ce format permet de setter des valeurs null, supprimer des noeuds, mettre à jour des tableaux …

Par contre, je lui trouve quand même un inconvénient à ce format: ce n’est pas très lisible dès qu’il y a un certain nombre d’opérations.

Au premier coup d’œil, il peut être difficile de voir ce qui est mis à jour (contrairement à JSON Merge Patch).

Conclusion

De mon point de vue, JSON Patch se démarque de JSON Merge Patch, car ce dernier est trop limité fonctionnellement.

Pour en savoir plus: JSON Patch

Laisser un commentaire

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