Verwenden des If-Match HTTP-Headers in PUT- und PATCH-Vorgängen

Für REST-Endpunkte möchten Entwickler häufig steuern, ob Updates neue Datensätze erstellen oder nur vorhandene ändern. Der If-Match HTTP-Header stellt dieses Steuerelement im Daten-API-Generator (DAB) bereit.

Standardmäßig werden DAB-Vorgänge behandelt PUT und PATCH als Upsert-Vorgänge verwendet:

• Wenn die Ressource vorhanden ist: DAB aktualisiert sie.

• Wenn sie nicht vorhanden ist: DAB fügt sie ein.

  • PUT → vollständigen Upsert (ersetzt Ressource).
  • PATCH → inkrementellen Upsert (gilt für partielle Aktualisierung).

Hinzufügen von If-Match: * Änderungen dieses Verhaltens zur reinen Semantik.

Funktionsweise von If-Match in DAB

If-Match wird nur mit dem Wildcardwert *unterstützt.

Verhaltensübersicht

• DAB implementiert keine ETag- oder Versionsabgleiche pro Datensatz.
• Es wird kein Parallelitätstoken ausgewertet. * behauptet nur", dass "vorhanden" ist.
• Gilt nur für REST, nicht für GraphQL.
• Für DELETE-Vorgänge ist derzeit nicht sinnvoll.

Verwenden von If-Match mit PUT

Ohne If-Matchwird PUT eingefügt, wenn die Ressource nicht vorhanden ist (gibt zurück 201 Created).

Beispiel für "Nur Aktualisieren"

Anforderung

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

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

Erfolg (Datensatz vorhanden)

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

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

Fehler (Datensatz fehlt)

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

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

Upsert insert example (no If-Match and record didn't exist)

Anforderung

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

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

Antwort

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

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

Verwenden von If-Match mit PATCH

PATCH verhält sich ähnlich. Ohne If-Matchwird ein inkrementeller Upsert ausgeführt. Mit diesem Element If-Match: *werden nur vorhandene Zeilen aktualisiert.

Anforderung

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

{
  "title": "The Two Towers"
}

Antwort beim Erfolg

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

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

Antwort, wenn nicht gefunden

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

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

Ungültige verwendung von If-Match

Alle anderen Werte als * (einschließlich an zitierter Zeichenfolgen) werden abgelehnt.

Anforderung

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

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

Antwort

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

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

Bewertung

• If-Match Lassen Sie die Upsert-Semantik (Einfüge-oder-Update-Semantik) aus.
• Wird If-Match: * für die strikte Nur-Update-Semantik verwendet (404, wenn das Element fehlt).
• Verwenden Sie keinen anderen Wert. Der echte ETag-Abgleich ist nicht implementiert.