Fale sobre o método PUT na API REST.

O método PUT é utilizado para criar ou atualizar um recurso na URI especificada.

Características principais:

• Idempotência: A execução repetida do mesmo pedido PUT com o mesmo corpo levará ao mesmo estado do recurso no servidor (embora a resposta do servidor possa variar).
• Substituição completa: O pedido PUT envia uma representação completa do recurso, substituindo a existente.
• Criação ou atualização: Se o recurso na URI especificada não existir, o PUT o cria. Se existir, atualiza-o. A ausência do recurso numa requisição PUT bem-sucedida geralmente leva à criação, que normalmente devolve o estado 201 Created. A atualização de um recurso existente normalmente devolve 200 OK ou 204 No Content (se não houver corpo na resposta).

Cenários de uso típicos:

• Atualização do perfil completo do utilizador.
• Criação de recurso se o cliente definir a sua URI.

Exemplo de requisição PUT:

PUT /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "id": 123,
  "name": "Novo Nome",
  "email": "new.email@example.com"
}

O servidor receberá esta requisição e criará um utilizador com id=123 ou substituirá completamente as informações do utilizador com esse ID pelos dados do corpo da requisição.

O PUT difere do POST no seguinte:

• O PUT é utilizado para atualizar ou criar um recurso em uma URI conhecida, que é definida pelo cliente. O POST é utilizado para criar um recurso, onde o servidor define a URI do novo recurso, ou para outras ações que não se enquadram em outros métodos HTTP.
• O PUT é idempotente, o POST não é. Requisições POST repetidas com o mesmo corpo podem criar múltiplos recursos iguais ou causar efeitos secundários diferentes.

Tabela comparativa entre PUT e POST:

Característica	PUT	POST
Propósito	Criar ou atualizar um recurso	Criar recurso, enviar dados
Idempotência	Sim	Não
Definição de URI	Pelo cliente	Pelo servidor
Impacto no recurso	Substitui ou cria completamente	Normalmente adiciona ou realiza uma ação