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 PATCH jako s operacemiPUT upsertu:

• Pokud prostředek existuje: aktualizuje se.

• Pokud neexistuje: vloží se.

  • 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

Žádost

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

{
  "title": "The Return of the King"
}

Úspěch (záznam existoval)

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

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

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)

Žádost

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

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

Odezva

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.

Žádost

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.

Žádost

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

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

Odezva

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

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

Review

• 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.