Použití If-Match hlavičky HTTP v operacích PUT a PATCH

U koncových bodů REST často chtějí vývojáři mít kontrolu nad tím, jestli aktualizace vytvářejí nové záznamy nebo jenom upravují existující záznamy. Hlavička If-Match HTTP poskytuje ovládací prvek v Tvůrci rozhraní DATA API (DAB).

DaB ve výchozím nastavení zachází s operacemi upsertu a PUT jako PATCH upsertu:

  • Pokud prostředek existuje: DAB ho aktualizuje.

  • Pokud neexistuje: DAB ho vloží.

    • PUT → úplné upsert (nahrazuje prostředek).
    • PATCH → přírůstkové upsert (platí částečnou aktualizaci).

Přidání If-Match: * změn tohoto chování na sémantiku pouze aktualizace.

Co If-Match dělá DAB

If-Matchse podporuje pouze se zástupným znakem .*

Hodnota záhlaví Chování
If-Match: * Provést aktualizaci pouze v případě, že prostředek existuje; Pokud chybí → 404 Nenalezena.
If-Match: <any other> Odmítnutý; 400 Chybný požadavek (Etags not supported, use '*').
(chybí) Chování upsertu (vložení, pokud nebylo nalezeno, jinak aktualizace)

Přehled chování

  • DAB neimplementuje značky ETag pro jednotlivé záznamy ani porovnávání verzí.
  • Nevyhodnocuje se žádný token souběžnosti. * pouze výrazy "musí existovat".
  • Platí jenom pro REST, nikoli GraphQL.
  • V současné době není pro operace DELETE smysluplné.

Použití If-Match s metodou PUT

Bez If-Matchpříkazu PUT se vloží, pokud prostředek neexistuje (vrátí 201 Created).

Příklad pouze aktualizace

Důležité

Protože PUT provádí úplné nahrazení, text požadavku musí obsahovat všechny sloupce bez hodnoty null. Vynechání požadovaného sloupce způsobí 400 Bad Request chybu databáze, i když If-Match: * je k dispozici. PUT Místo PATCH toho použijte, pokud chcete odeslat jenom podmnožinu polí.

Prosba

PUT /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Return of the King",
  "publisher_id": 7
}

Úspěch (záznam existoval)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Return of the King",
  "publisher_id": 7
}

Selhání (chybějící záznam)

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Příklad vložení upsertu (žádný If-Match a záznam neexistuje)

Prosba

PUT /api/Books/id/500
Content-Type: application/json

{
  "title": "Inserted via PUT",
  "publisher_id": 7
}

odpověď

HTTP/1.1 201 Created
Location: id/500
Content-Type: application/json

{
  "id": 500,
  "title": "Inserted via PUT",
  "publisher_id": 7
}

Použití If-Match s nástrojem PATCH

PATCH chová se podobně. Bez If-Match, provádí přírůstkový upsert. Aktualizuje If-Match: *pouze existující řádky.

Prosba

PATCH /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Two Towers"
}

Odpověď při úspěchu

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Two Towers"
}

Odpověď, když nebyla nalezena

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Neplatné využití If-Match

Jakákoli jiná hodnota než * (včetně uvozových řetězců) se odmítne.

Prosba

PUT /api/Books/id/1
If-Match: "abc123"
Content-Type: application/json

{
  "title": "To Kill a Mockingbird"
}

odpověď

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Etags not supported, use '*'"
}

Recenze

  • Vynechání If-Match sémantiky upsertu (vložení nebo aktualizace).
  • Používá se If-Match: * pro striktní sémantiku pouze aktualizace (404, pokud položka chybí).
  • Nepoužívejte žádnou jinou hodnotu. Skutečné porovnávání značky ETag není implementováno.

Poznámka:

Funkce tvůrce rozhraní Data API 2.0 popsané v této části jsou aktuálně ve verzi Preview a můžou se změnit před obecnou dostupností. Další informace najdete v tématu Co je nového ve verzi 2.0.

  • Last updated on