Usar o cabeçalho HTTP If-Match em operações PUT e PATCH

Para pontos de extremidade REST, os desenvolvedores geralmente querem ter controle sobre se as atualizações criam novos registros ou apenas modificam os existentes. O If-Match cabeçalho HTTP fornece esse controle no Data API builder (DAB).

Por padrão, o PUT DAB trata e PATCH como operações de upsert :

• Se o recurso existir: ele é atualizado.

• Se não existir: está inserido.

  • PUT → upsert completo (substitui o recurso).
  • PATCH → upsert incremental (aplica atualização parcial).

A adição If-Match: * altera esse comportamento à semântica somente atualização.

O que If-Match faz no DAB

If-Match é suportado apenas com o valor *curinga .

Valor do Cabeçalho	Comportamento
If-Match: *	Execute a atualização somente se o recurso existir; se faltar → 404 Não encontrado.
If-Match: <any other>	Rejeitado; 400 Mau Pedido (Etags not supported, use '*').
(ausente)	Comportamento Upsert (inserir se não for encontrado, caso contrário, atualizar).

Visão geral do comportamento

• O DAB não implementa ETag por registro ou correspondência de versão.
• Nenhum token de simultaneidade é avaliado. * apenas afirma "deve existir".
• Aplica-se apenas ao REST, não ao GraphQL.
• Atualmente não é significativo para operações DELETE.

Usando If-Match com PUT

Sem If-Match, PUT insere quando o recurso não existe (retorna 201 Created).

Exemplo somente de atualização

Solicitação

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

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

Sucesso (recorde existente)

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

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

Falha (registro ausente)

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

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

Upsert inserir exemplo (nenhum If-Match e registro não existia)

Solicitação

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

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

Resposta

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

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

Usando If-Match com PATCH

PATCH comporta-se de forma semelhante. Sem If-Match, ele executa um upsert incremental. Com If-Match: *o , ele atualiza apenas as linhas existentes.

Solicitação

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

{
  "title": "The Two Towers"
}

Resposta quando o sucesso

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

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

Resposta quando não encontrado

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

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

Uso de If-Match inválido

Qualquer valor diferente ( * incluindo cadeias de caracteres entre aspas) é rejeitado.

Solicitação

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

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

Resposta

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

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

Revisão

• Omitir If-Match para semântica upsert (inserir ou atualizar).
• Use If-Match: * para semântica somente atualização estrita (404 se o item estiver faltando).
• Não use nenhum outro valor. A correspondência de ETag real não é implementada.