JSON Patch a JSON Merge Patch

Šest operací JSON Patch

[
  {
    "op": "test",
    "path": "/verze",
    "value": 3
  },
  {
    "op": "replace",
    "path": "/zakaznik/jmeno",
    "value": "Eva"
  },
  {
    "op": "add",
    "path": "/polozky/-",
    "value": {
      "nazev": "Talíř",
      "cena": 99
    }
  },
  {
    "op": "remove",
    "path": "/sleva"
  }
]

Každá operace se vyhodnocuje nad výsledkem předchozí. Cesty v path a from jsou JSON Pointer. V ukázce musí původní dokument obsahovat verzi 3, zákazníka s jménem, pole položek a slevu.

Přidání do pole položku vloží a posune indexy dalších. /- přidá na konec. replace i remove vyžadují existující cíl; add může vytvořit poslední člen, ale nevytváří automaticky chybějící rodiče.

Pořadí, test a selhání

Při chybě se další operace nevykonávají. Při HTTP PATCH se musí všechny změny provést společně: při chybě nesmí zůstat uložený částečný výsledek. Knihovna sama ale může při chybě ponechat částečně upravený pracovní objekt. Použij kopii nebo transakci.

test pomáhá ověřit očekávaný stav, ale nenahrazuje autorizaci ani správné řízení souběhu na serveru. Pro aktualizaci API zvaž také ETag a If-Match. Přesun rodiče do vlastního potomka není povolený.

JSON Merge Patch (RFC 7396)

{"zakaznik":{"jmeno":"Eva"},"sleva":null}

V objektovém patchi se vlastnosti přidají nebo změní rekurzivně. null zde znamená odstranění vlastnosti, takže nelze tímto zápisem nastavit explicitní null. Pole se nahrazují celé, ne po položkách. Neobjektový patch nahradí celý cíl.

Merge Patch je vhodný pro jednodušší aktualizace objektů bez významových null hodnot. Pro přesné zásahy do polí a nastavení null použij JSON Patch.

Bezpečnost a diagnostika

• Kontroluj povolené operace a cesty; klient nesmí měnit například vlastní roli.
• Omez počet operací i velikost výsledku.
• Validuj výsledná data schématem a aplikačními pravidly.
• Po odstranění z pole se další indexy změní; testuj pořadí.

Srovnání adresování a dotazování najdeš v přehledu JSONPath, Pointer a Patch.

Všech šest operací na jednom dokumentu

{"verze":1,"tagy":["xml","json"],"nazev":"Starý"}

[
  {
    "op": "test",
    "path": "/verze",
    "value": 1
  },
  {
    "op": "replace",
    "path": "/nazev",
    "value": "Nový"
  },
  {
    "op": "add",
    "path": "/tagy/-",
    "value": "schema"
  },
  {
    "op": "copy",
    "from": "/nazev",
    "path": "/kopie"
  },
  {
    "op": "move",
    "from": "/kopie",
    "path": "/titulek"
  },
  {
    "op": "remove",
    "path": "/tagy/0"
  }
]

{"verze":1,"tagy":["json","schema"],"nazev":"Nový","titulek":"Nový"}

Test vyžaduje původní verzi. Replace mění existující položku; add může vytvořit vlastnost nebo vložit položku do pole. Zvláštní - znamená v add konec pole. Copy zachová zdroj, move jej odstraní. Remove odstraní první tag a ostatní indexy se posunou.

Pokud test selže, následující operace se nemají vykonat. Zpracování HTTP PATCH musí provést všechny změny společně, nebo při chybě žádnou neuložit: neukládej po každé instrukci částečný stav. Knihovna může při chybě změnit pracovní objekt, proto pracuj s kopií a výsledek ulož až po úspěchu a datové validaci.

Patch nemá implicitní právo měnit každou cestu: server musí povolit konkrétní vlastnosti a znovu ověřit oprávnění. Klientský test verze pomáhá s konkurencí, ale skutečnou kontrolu aktuálního stavu musí provést server. Pravidla operací definuje RFC 6902.