PUT vs PATCH: qual usar para atualizar um recurso

Os dois atualizam um recurso, mas com semânticas diferentes — e escolher errado costuma apagar campos que ninguém pediu para apagar.

Comparação direta

	PUT	PATCH
Significado	Substitui o recurso inteiro	Aplica alterações parciais
Corpo	A representação completa	Só os campos que mudam
Campos ausentes	São removidos ou zerados	Permanecem como estavam
Idempotente	Sim	Não necessariamente
Pode criar o recurso	Sim, na URL informada	Não

O erro que apaga campos

O engano mais comum é enviar um objeto parcial com PUT. Como o PUT substitui o recurso inteiro, tudo que não veio no corpo deveria ser removido — e APIs que implementam a semântica corretamente fazem isso.

http

# ✗ PUT com corpo parcial: o telefone é apagado
PUT /usuarios/7
{ "nome": "Ana" }

# ✓ PUT com o recurso completo
PUT /usuarios/7
{ "nome": "Ana", "email": "ana@exemplo.com", "telefone": "11999998888" }

# ✓ PATCH para alterar só um campo
PATCH /usuarios/7
{ "nome": "Ana" }

Idempotência na prática

PUT é idempotente: repetir a mesma requisição dez vezes deixa o recurso no mesmo estado da primeira. Isso permite que um cliente reenvie com segurança depois de um erro de rede.

PATCH pode não ser. Um patch que diz 'some 1 ao contador' muda o resultado a cada repetição. Um patch que diz 'defina o nome como Ana' é idempotente. A semântica depende do formato adotado.

Como decidir

O cliente tem o recurso inteiro e quer gravá-lo: PUT
O cliente quer alterar um ou dois campos: PATCH
A operação precisa ser segura para reenviar após timeout: PUT
O formulário edita o objeto completo: PUT casa melhor com a tela
Na dúvida, PATCH: ele nunca apaga o que você não mencionou

Perguntas frequentes

Qual status devolver em uma atualização bem-sucedida?: 200 com o recurso atualizado no corpo, ou 204 sem corpo. Use 201 apenas quando o PUT criou um recurso que ainda não existia, e devolva o header Location.
PATCH precisa de um formato específico?: As RFCs definem JSON Patch (application/json-patch+json) e JSON Merge Patch (application/merge-patch+json). Na prática, a maioria das APIs aceita um JSON parcial simples, o que equivale ao merge patch.

Resolva na prática

Guias relacionados

301 vs 302: qual redirecionamento usar e o impacto no SEO

PUT

PATCH

Significado

Substitui o recurso inteiro

Aplica alterações parciais

Corpo

A representação completa

Só os campos que mudam

Campos ausentes

São removidos ou zerados

Permanecem como estavam

Idempotente

Sim

Não necessariamente

Pode criar o recurso

Sim, na URL informada

Não

O erro que apaga campos

http

# ✗ PUT com corpo parcial: o telefone é apagado
PUT /usuarios/7
{ "nome": "Ana" }

# ✓ PUT com o recurso completo
PUT /usuarios/7
{ "nome": "Ana", "email": "ana@exemplo.com", "telefone": "11999998888" }

# ✓ PATCH para alterar só um campo
PATCH /usuarios/7
{ "nome": "Ana" }

Idempotência na prática

PUT é idempotente: repetir a mesma requisição dez vezes deixa o recurso no mesmo estado da primeira. Isso permite que um cliente reenvie com segurança depois de um erro de rede.

PATCH pode não ser. Um patch que diz 'some 1 ao contador' muda o resultado a cada repetição. Um patch que diz 'defina o nome como Ana' é idempotente. A semântica depende do formato adotado.

Perguntas frequentes

Qual status devolver em uma atualização bem-sucedida?

200 com o recurso atualizado no corpo, ou 204 sem corpo. Use 201 apenas quando o PUT criou um recurso que ainda não existia, e devolva o header Location.

PATCH precisa de um formato específico?

As RFCs definem JSON Patch (application/json-patch+json) e JSON Merge Patch (application/merge-patch+json). Na prática, a maioria das APIs aceita um JSON parcial simples, o que equivale ao merge patch.