De If-Match HTTP-header gebruiken in PUT- en PATCH-bewerkingen

Voor REST-eindpunten willen ontwikkelaars vaak bepalen of updates nieuwe records maken of alleen bestaande records wijzigen. De If-Match HTTP-header biedt dat besturingselement in Data API Builder (DAB).

DAB behandelt en PATCH als upsert-bewerkingenPUT standaard:

• Als de resource bestaat: deze wordt bijgewerkt.

• Als deze niet bestaat, wordt deze ingevoegd.

  • PUT → volledige upsert (vervangt de resource).
  • PATCH → incrementele upsert (gedeeltelijke update wordt toegepast).

Wijzigingen aan dit gedrag toevoegen If-Match: * om semantiek alleen bij te werken.

Wat If-Match doet in DAB

If-Match wordt alleen ondersteund met de jokertekenwaarde *.

Headerwaarde	Gedrag
If-Match: *	Alleen bijwerken als de resource bestaat; als → 404 niet gevonden is.
If-Match: <any other>	Afgekeurd; 400 Ongeldige aanvraag (Etags not supported, use '*').
(afwezig)	Upsert-gedrag (invoegen indien niet gevonden, anders bijwerken).

Overzicht van gedrag

• DAB implementeert geen ETag- of versiekoppeling per record.
• Er wordt geen gelijktijdigheidstoken geëvalueerd. * alleen asserties 'moeten bestaan'.
• Alleen van toepassing op REST, niet Op GraphQL.
• Momenteel niet zinvol voor DELETE-bewerkingen.

If-Match gebruiken met PUT

Zonder If-Matchwordt PUT ingevoegd wanneer de resource niet bestaat (retourneert).201 Created

Voorbeeld van alleen-bijwerken

Aanvraag

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

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

Geslaagd (record bestaat)

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

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

Fout (record ontbreekt)

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

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

Voorbeeld van upsert-invoeging (geen If-Match en record bestond niet)

Aanvraag

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

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

Reactie

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

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

If-Match gebruiken met PATCH

PATCH gedraagt zich op dezelfde manier. Zonder If-Matchvoert het een incrementele upsert uit. Hiermee If-Match: *worden alleen bestaande rijen bijgewerkt.

Aanvraag

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

{
  "title": "The Two Towers"
}

Antwoord wanneer geslaagd

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

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

Antwoord wanneer niet gevonden

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

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

Ongeldig If-Match gebruik

Een andere waarde dan * (inclusief tekenreeksen tussen aantekeningen) wordt geweigerd.

Aanvraag

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

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

Reactie

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

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

Review

• If-Match Laat de semantiek van upsert (insert-or-update) weg.
• Gebruik If-Match: * deze optie voor strikte semantiek (404 als het item ontbreekt).
• Gebruik geen andere waarde. Echte ETag-overeenkomsten worden niet geïmplementeerd.