No design RESTful de API, PUT e PATCH são dois métodos HTTP usados para atualizar recursos no servidor, mas a diferença entre PUT vs PATCH em REST APIs está em como executam as atualizações e os cenários em que cada um é mais apropriado. Ambos os métodos são projetados para modificar dados existentes, mas entender a diferença entre PUT e PATCH em REST API ajuda desenvolvedores a fazer a melhor escolha com base na natureza da atualização que precisam executar. Neste artigo, exploraremos a diferença entre PUT e PATCH em REST API, focando no debate PATCH vs atualização em REST, quando usar cada um, e forneceremos orientação para escolher o método certo para diferentes casos de uso.
O que é PUT em REST APIs?
Para entender a diferença entre PUT e PATCH em REST APIs, primeiro precisamos saber o que é PUT. De acordo com Seção 9.6 RFC 2616, o método PUT em REST API solicita que a entidade enviada seja armazenada sob a Request-URI fornecida.
Se a Request-URI refere-se a um recurso já existente, a entidade enviada DEVE ser considerada como uma versão modificada daquele residente no servidor de origem. Se a Request-URI não aponta para um recurso existente e esse URI pode ser definido como um novo recurso pelo agente de usuário solicitante, o servidor de origem pode criar o recurso com esse URI.
Em outras palavras, o método PUT é usado para atualizar um recurso inteiro no servidor. Isso torna PUT uma atualização mais "completa", frequentemente usada quando uma substituição total do recurso é necessária.
Por isso, PUT é ideal para os seguintes casos de uso:
- Atualizar um recurso completo (por exemplo, atualizar um perfil de usuário com todas as novas informações).
- Substituir um item ou registro inteiro.
- Quando a identidade do recurso é clara e seus dados precisam ser completamente renovados.
I need the complete text to translate. You've only provided "In systems like" which appears to be incomplete. Could you please provide the full phrase or sentence you'd like me to translate to Portuguese? Elasticsearch, operações idempotentes são necessárias para garantir consistência de dados. Por exemplo, atualizar um documento em Elasticsearch usando PUT garante que a mesma requisição possa ser repetida sem efeitos colaterais indesejados.
O que é PATCH em REST APIs?
Agora que cobrimos PUT em REST APIs, vamos ver o que é PATCH em REST APIs e como funciona antes de compararmos PUT vs PATCH em REST APIs. Conforme definido em RFC 5789, o método PATCH em REST API solicita que um conjunto de mudanças descritas na entidade da requisição seja aplicado ao recurso identificado pela Request-URI.
Isso se alinha com a distinção PUT vs PATCH REST API, onde você envia apenas os dados que precisam ser modificados, e o servidor aplica essas mudanças ao recurso existente sem alterar o recurso inteiro. Desenvolvedores frequentemente criam patches para representar essas mudanças incrementais, garantindo transferência mínima de dados e atualizações eficientes.
Por isso o método PATCH em REST API é melhor adequado para os seguintes casos de uso:
- Atualizar apenas um subconjunto de campos em um recurso (por exemplo, alterar o endereço de email ou número de telefone de um usuário). Um exemplo de PATCH API poderia envolver apenas o novo email, deixando outros campos intactos.
- Melhorar o desempenho minimizando a carga de dados.
- Quando você quer atualizar um recurso incrementalmente em vez de substituí-lo completamente.
- Crie patches para encapsular mudanças de campos específicos, como modificar o email de um usuário, sem afetar dados não relacionados.
Para plataformas como CMS headless que frequentemente lidam com estruturas de conteúdo complexas, usar PATCH para pequenas atualizações - como modificar um único campo - pode reduzir a carga do servidor e melhorar o desempenho.
Com esses dois métodos cobertos, você deve ter uma ideia razoável do que são PUT e PATCH em REST APIs. Porém, antes de entrarmos na diferença entre PUT vs PATCH em REST APIs, precisamos falar sobre Idempotência nesses dois métodos.
Idempotência em PUT vs PATCH em REST APIs
Em REST APIs, idempotência refere-se à propriedade de uma operação que, quando repetida várias vezes com as mesmas entradas, produz o mesmo resultado. Isso significa que fazer a mesma requisição várias vezes deve ter o mesmo efeito no servidor, independentemente de quantas vezes seja executada. Isso é importante para garantir estabilidade e previsibilidade em um API. Mas como isso é relevante para a diferença entre PUT e PATCH em REST API?
Método PUT e Idempotência
O método PUT em REST API é sempre idempotente porque foi projetado para substituir o recurso inteiro em uma URI especificada pelos dados fornecidos na requisição. Em outras palavras, se você executar uma requisição PUT várias vezes com os mesmos dados de recurso, o resultado será sempre o mesmo.
Por que PUT é Idempotente? Quando você faz uma requisição PUT, está essencialmente dizendo ao servidor: "Este é o estado completo e exato que quero para este recurso." Quer você envie a requisição PUT uma ou várias vezes, o recurso resultante será sempre idêntico.
Por exemplo, considere o cenário em que você atualiza o endereço de email de um usuário. Se você fizer a mesma requisição PUT várias vezes, o resultado não será alterado porque o recurso é substituído pelos mesmos dados a cada vez.
Exemplo:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Se você enviar esta requisição várias vezes, o resultado será sempre o mesmo:
| {"username": "john_doe","email": "[email protected]"} |
Mesmo que os dados do usuário já sejam assim, enviar a requisição novamente não muda nada. Ele substitui os dados pelos mesmos dados, então o efeito da requisição permanece o mesmo independentemente de quantas vezes seja repetida. Isso é o que torna PUT idempotente.
Método PATCH e Idempotência
O método PATCH em REST API, por outro lado, é geralmente idempotente também, mas com mais flexibilidade. Quando você cria patches, certifique-se de que as operações são idempotentes (por exemplo, definir um valor) para evitar efeitos colaterais indesejados de requisições repetidas. Se PATCH é idempotente depende da operação e dos dados sendo modificados.
Por que PATCH é Idempotente? Para requisições PATCH, idempotência significa que aplicar o mesmo patch várias vezes terá o mesmo resultado. Isso é verdade contanto que o patch em si não cause efeitos colaterais adicionais ou mudanças quando aplicado repetidamente. Se você continuar aplicando o mesmo patch com os mesmos dados, o resultado deve ser inalterado após a primeira aplicação.
Por exemplo, se você está apenas atualizando o email de um usuário, enviar repetidamente a mesma requisição PATCH não mudará o resultado após a primeira vez, mesmo que a requisição seja feita várias vezes. O email do usuário permanecerá o mesmo, e o estado do recurso não mudará.
Exemplo PATCH API:
| PATCH /users/1{"email": "[email protected]"} |
Se o email já era [email protected], aplicar este PATCH novamente resultará em nenhuma mudança, tornando-o idempotente.
No entanto, PATCH também pode ser não-idempotente em alguns casos. Por exemplo, se uma operação PATCH modifica um contador ou adiciona itens a uma lista (como incrementar um número ou adicionar a um array), aplicações repetidas do mesmo PATCH podem levar a resultados diferentes. Isso violaria a propriedade de idempotência.
Exemplo PATCH não-idempotente API REST:
| PATCH /counter/1{"increment": 1} |
Se você aplicar este PATCH repetidamente, o contador continuará aumentando, resultando em valores diferentes a cada vez. Isso não é idempotente porque o resultado muda com cada aplicação.
Agora que você conhece o essencial, podemos analisar alguns cenários de exemplo para entender melhor a diferença entre PUT vs PATCH em REST APIs.
Cenários de Exemplo: PUT vs PATCH em REST APIs
Deixando a teoria de lado, vejamos a diferença entre PUT e PATCH com exemplos, incluindo operações idempotentes e não-idempotentes.
Cenário 1: Requisição PUT – Substituindo um Recurso Inteiro
Imagine um endpoint API para gerenciar produtos em um sistema de comércio eletrônico. Você precisa atualizar todos os detalhes de um produto, incluindo seu nome, preço e descrição. Este é um exemplo típico de HTTP PUT vs PATCH, onde PUT é usado para substituir o recurso de produto completo.
Produto Inicial:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Você quer atualizar o preço e a descrição do produto. Você envia uma requisição PUT com o recurso inteiro:
Solicitação PUT:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Se você fizer esta solicitação PUT uma ou várias vezes, o resultado será sempre o mesmo. Os detalhes do produto serão atualizados para refletir o novo preço e descrição, e o mesmo resultado ocorrerá a cada vez. Isso garante a natureza idempotente do PUT.
Resultado (Após solicitação PUT):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Cenário 2: Solicitação PATCH – Atualizando parte de um recurso
Agora, considere uma solicitação PATCH para atualizar apenas parte dos detalhes do produto, como a descrição. PATCH API exemplo: se você quiser alterar a descrição do produto mas não seu preço, PATCH é a melhor escolha. Para implementar isso, você criaria patches contendo apenas os campos que precisam ser modificados, como a descrição neste API REST exemplo PATCH.
Produto Inicial:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Solicitação PATCH:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Quando você envia esta solicitação PATCH, apenas o campo de descrição será atualizado. Se você enviar a mesma solicitação PATCH várias vezes, a descrição permanecerá inalterada após a primeira atualização, tornando a solicitação idempotente.
Resultado (Após solicitação PATCH):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Se você aplicar o mesmo PATCH novamente, a descrição do produto continuará a mesma de após o primeiro PATCH. O resultado é consistente, o que torna o PATCH idempotente neste cenário.
Cenário 3: Solicitação PATCH – Operação não idempotente
Vamos analisar uma operação PATCH não idempotente. Suponha que haja um endpoint para o saldo da carteira de um usuário, e você queira incrementar o saldo. Uma diferença de exemplo entre PUT e PATCH pode ser ilustrada aqui: PATCH adicionará um valor ao saldo a cada vez
Carteira Inicial:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Solicitação PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
Esta solicitação PATCH aumentará o saldo da carteira em $50. Se você enviar esta solicitação PATCH várias vezes, o saldo continuará aumentando a cada PATCH, resultando em um resultado diferente a cada vez. Isso não é idempotente porque aplicar o mesmo PATCH repetidamente causará um resultado diferente.
Resultado (Após primeira solicitação PATCH):
| {"id": 1,"balance": 150.00} |
Resultado (Após segunda solicitação PATCH):
| {"id": 1,"saldo": 200.00} |
Aqui, PATCH não é idempotente porque solicitações repetidas com os mesmos dados produzem resultados diferentes.
Resumo: Principais Diferenças Entre PUT e PATCH em REST APIs
A diferença-chave entre PUT versus PATCH em REST API é como eles lidam com atualizações. PUT substitui o recurso inteiro, então campos ausentes são apagados, o que pode levar à perda de dados. É por isso que os desenvolvedores criam patches para atualizações parciais, a fim de evitar sobrescrever campos inalterados e manter a integridade dos dados.
Isso torna o PATCH mais eficiente para atualizações parciais. Um API exemplo PATCH é que se você quiser atualizar apenas o email de um usuário, criar patches enviaria apenas o campo de email, diferentemente de uma solicitação PUT que exigiria todos os dados do usuário.
Com PUT, a carga de dados completa é necessária. Isso significa que cada campo deve ser enviado, e campos ausentes serão apagados. PATCH, no entanto, envia apenas os campos que precisam ser atualizados, tornando-o mais eficiente, especialmente para recursos grandes com mudanças mínimas. O método PATCH em REST API permite solicitações mais focadas e menores, reduzindo a transferência de dados.
Tanto PUT quanto PATCH são idempotentes. Isso significa que repetir a mesma solicitação resultará no mesmo resultado. No entanto, PUT é mais previsível, pois substitui o recurso inteiro. PATCH, quando usado para modificar apenas campos especificados, pode levar a resultados diferentes dependendo de como as atualizações são tratadas pelo servidor.
Por exemplo, se um PATCH incrementa um contador, solicitações repetidas podem levar a resultados diferentes. Apesar disso, operações PATCH API também podem ser projetadas para serem idempotentes.
Em conclusão, a diferença entre PUT e PATCH em REST API se resume à natureza das atualizações: PATCH é para mudanças parciais, enquanto PUT é para substituição completa de recursos. Ambos são idempotentes, mas PATCH pode ser mais complexo.
Pensamentos Finais
Tanto PUT quanto PATCH são métodos fundamentais HTTP em design REST API, mas servem a propósitos diferentes, o que é a essência da diferença entre PUT e PATCH em REST API. Você pode melhorar significativamente a eficiência, clareza e funcionalidade do seu API compreendendo a diferença entre PUT e PATCH com os exemplos que abordamos anteriormente neste artigo. Ao escolher o método correto (PATCH versus atualizar REST) com base no seu caso de uso, você pode tornar seu API mais eficiente, mantível e fácil de usar. Sempre considere a natureza da atualização, se é completa ou parcial, juntamente com o impacto no desempenho e integridade dos dados, e selecione o método que melhor se alinha às suas necessidades.
