Używanie nagłówka HTTP If-Match w operacjach PUT i PATCH

W przypadku punktów końcowych REST deweloperzy często chcą kontrolować, czy aktualizacje tworzą nowe rekordy, czy modyfikują tylko istniejące. Nagłówek HTTP udostępnia kontrolkę w narzędziu If-Match Data API Builder (DAB).

Domyślnie daB traktuje operacje PUT upsert i PATCH jako operacje upsert :

• Jeśli zasób istnieje: jest aktualizowany.

• Jeśli nie istnieje: jest wstawiony.

  • PUT → pełnej operacji upsert (zastępuje zasób).
  • PATCH → przyrostowe upsert (stosuje częściową aktualizację).

Dodawanie If-Match: * zmian tego zachowania do semantyki tylko aktualizacji.

Co If-Match robi w języku DAB

If-Match jest obsługiwany tylko w przypadku wartości *wieloznacznych .

Wartość nagłówka	Zachowanie
If-Match: *	Przeprowadź aktualizację tylko wtedy, gdy zasób istnieje; jeśli brakuje → 404 Nie znaleziono.
If-Match: <any other>	Odrzucone; 400 Nieprawidłowe żądanie (Etags not supported, use '*').
(nieobecny)	Zachowanie operacji upsert (wstaw, jeśli nie znaleziono, w przeciwnym razie zaktualizuj).

Omówienie zachowania

• Język DAB nie implementuje elementu ETag dla rekordu ani dopasowania wersji.
• Nie ocenia się tokenu współbieżności. * tylko asercyjnie "musi istnieć".
• Dotyczy tylko rest, a nie GraphQL.
• Obecnie nie ma znaczenia dla operacji DELETE.

Używanie If-Match z funkcją PUT

Bez If-Matchmetody funkcja PUT wstawia, gdy zasób nie istnieje (zwraca wartość 201 Created).

Przykład tylko do aktualizacji

Żądanie

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

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

Powodzenie (rekord istniał)

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

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

Błąd (brak rekordu)

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

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

Przykład wstawiania upsert (nie If-Match i rekord nie istnieje)

Żądanie

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

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

Odpowiedź

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

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

Używanie If-Match z poprawką PATCH

PATCH zachowuje się podobnie. Bez If-Matchparametru wykonuje przyrostowe operacje upsert. W programie If-Match: *aktualizuje tylko istniejące wiersze.

Żądanie

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

{
  "title": "The Two Towers"
}

Odpowiedź w przypadku powodzenia

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

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

Odpowiedź, gdy nie znaleziono

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

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

Nieprawidłowe użycie If-Match

Każda wartość inna niż * (w tym ciągi cytowane) jest odrzucana.

Żądanie

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

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

Odpowiedź

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

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

Wykonaj przegląd

• Pomijanie If-Match semantyki operacji upsert (insert-or-update).
• Służy If-Match: * do ścisłej semantyki tylko aktualizacji (404, jeśli brakuje elementu).
• Nie używaj żadnej innej wartości. Dopasowanie rzeczywistego elementu ETag nie jest implementowane.