Що таке JSON Patch?

Для деяких об’єктів Edibox підтримує використання формату JSON Patch.

JSON Patch - це формат обміну даних, який дозволяє частково змінювати дані об’єкта через REST API використовуючи метод PATCH. Формат цих операцій детально описано в стандарті RFC-6902.

Зазвичай для таких запитів використовуються тип даних (content-type), application/json-patch+json, однак Edibox також дозволяє використати звичайний application/json.

Структура об’єкта

JSON Patch запит - це json з масивом об’єктів. Кожен об’єкт представляє одну операцію, яка повинна бути виконана на цільовому об’єкті.

Запит для модифікації даних

PATCH /my/data HTTP/1.1
Host: example.org
Content-Length: 326
Content-Type: application/json-patch+json

[
  { "op": "test", "path": "/a/b/c", "value": "foo" },
  { "op": "remove", "path": "/a/b/c" },
  { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
  { "op": "replace", "path": "/a/b/c", "value": 42 },
  { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
  { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
]

Кожна з операції буде застосовуватися до цільового об’єкта по черзі. Після виконання кожної чергової операції змінений об’єкт стає цільовим для наступної операції.

Якщо будь-яка з операції завершується помилкою, то сервер також скасовує всі попередні модифікації, повертаючи повідомлення про помилку.

Приклад використання

Наприклад, є запит https://example.com/api/items/123, де можна переглянути вміст об’єкта 123.

Об’єкт "123"

{
  "id": 123,
  "name": "Object 1",
  "total": 42,
  "is_enabled": true
}

Використання JSON Patch дозволяє при потребі змінити одне або декілька з його полів.

Щоб змінити поля name та total, потрібно виконати один запит PATCH https://example.com/api/items/123 у форматі JSON Patch.

JSON Patch для зміни name та total

[
  { "op": "replace", "path": "/name", "value": "My object 123"},
  { "op": "add", "path": "/total", "value": 99}
]

В даному прикладі операції add та replace є синонімами: обидві операції призведуть до заміни попереднього значення в об’єкта 123 на нове.

Після виконання запиту об’єкт "123" виглядатиме наступним чином:

Об’єкт після успішного виконання запиту

{
  "id": 123,
  "name": "My object 123",
  "total": 99,
  "is_enabled": true
}

Змінити можна тільки заздалегідь визначений розробниками перелік полів. Наприклад, у наведеному прикладі може бути заборонено змінювати поле зі шляхом /id - тому спроба це зробити завершиться помилкою.