Uso del encabezado HTTP de If-Match en operaciones PUT y PATCH

En el caso de los puntos de conexión REST, los desarrolladores suelen querer controlar si las actualizaciones crean registros nuevos o solo modifican las existentes. El If-Match encabezado HTTP proporciona ese control en Data API Builder (DAB).

De forma predeterminada, DAB trata PUT y PATCH como operaciones upsert :

• Si el recurso existe: se actualiza.

• Si no existe, se inserta.

  • PUT → upsert completo (reemplaza el recurso).
  • PATCH → upsert incremental (aplica una actualización parcial).

Agregar If-Match: * cambios en este comportamiento a la semántica de solo actualización.

Qué If-Match hace en DAB

If-Match solo se admite con el valor *comodín .

Valor de encabezado	Comportamiento
If-Match: *	Realice la actualización solo si el recurso existe; si falta → no encontrado 404.
If-Match: <any other>	Rechazado; 400 Solicitud incorrecta (Etags not supported, use '*').
(ausente)	Comportamiento de upsert (inserte si no se encuentra; de lo contrario, actualice).

Información general sobre el comportamiento

• DAB no implementa la coincidencia de ETag por registro o versión.
• No se evalúa ningún token de simultaneidad. * solo afirma "debe existir".
• Solo se aplica a REST, no a GraphQL.
• Actualmente no es significativo para las operaciones DELETE.

Uso de If-Match con PUT

Sin If-Match, PUT inserta cuando el recurso no existe (devuelve 201 Created).

Ejemplo de solo actualización

Solicitud

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

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

Correcto (registro existente)

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

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

Error (falta el registro)

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

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

Ejemplo de inserción upsert (no If-Match y el registro no existían)

Solicitud

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

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

Respuesta

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

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

Uso de If-Match con PATCH

PATCH se comporta de forma similar. Sin If-Match, realiza un upsert incremental. Con If-Match: *, solo actualiza las filas existentes.

Solicitud

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

{
  "title": "The Two Towers"
}

Respuesta cuando se realiza correctamente

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

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

Respuesta cuando no se encuentra

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

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

Uso de If-Match no válido

Se rechaza cualquier valor distinto * de (incluidas las cadenas entre comillas).

Solicitud

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

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

Respuesta

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

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

Revisión

• Omita If-Match la semántica upsert (insert-or-update).
• Use If-Match: * para la semántica estricta de solo actualización (404 si falta el elemento).
• No use ningún otro valor. No se implementa la coincidencia de ETag real.