O que é o método PUT?

O método PUT

O método HTTP PUT tem uma função. Ele substitui o recurso numa URL específica, ou o cria se ele ainda não existir.

Diferente do POST, que diz "Aqui estão alguns dados, servidor, por favor crie um novo item para mim", o PUT diz "Pegue estes dados e coloque-os nesta URL."

Uma analogia do mundo real

Imagine que você está atualizando sua foto de perfil em um site de rede social.

• Se você usar POST (como criar uma nova postagem), o servidor pode criar uma nova URL a cada vez: /photos/123, e depois /photos/124, etc.
• Se você usar PUT para /users/joaosilva/foto-de-perfil, você está dizendo "Torne esta imagem a foto de perfil nesta URL exata." Se já houver uma foto lá, ela será sobrescrita. Se não houver, ela será criada.

O comportamento de "upsert"

O PUT pode atualizar um item existente ou criar um novo se ele não existir. Por isso costuma ser descrito como uma operação de "Upsert" (Update + Insert, ou Atualizar + Inserir).

Se você enviar uma requisição PUT para /articles/10 e o artigo nº 10 já existir, o servidor substitui o artigo nº 10 pelos seus novos dados. Se ele não existir, o servidor pode criar um artigo novo com o ID 10. Isso depende do design da API.

Substituição completa

Uma regra crítica do método PUT é que ele representa uma substituição completa do recurso.

Se um objeto User possui name, email e age (idade), e você deseja atualizar apenas a age para 30 usando PUT, você não pode enviar apenas { "age": 30 }.

Você deve enviar a representação inteira do usuário: { "name": "Joao Silva", "email": "[email protected]", "age": 30 }.

Se você enviar apenas a age (idade), uma implementação estrita do PUT vai excluir os campos name e email ou defini-los como nulos. Você pediu uma substituição total, e é isso que recebe.

Resumo