No design da API RESTful, PUT e PATCH são dois métodos HTTP usados para atualizar recursos no servidor, mas a diferença entre PUT e PATCH em APIs REST está na forma como eles executam as atualizações e nos cenários em que cada um é mais apropriado. Ambos os métodos são projetados para modificar dados existentes, mas compreender a diferença entre PUT e PATCH na API REST pode ajudar os desenvolvedores a fazer a melhor escolha com base na natureza da atualização que precisam realizar. Nesta postagem do blog, exploraremos a diferença entre PUT e PATCH na API REST, focando no debate PATCH vs update REST, quando usar cada um, e forneceremos orientação sobre como escolher o método certo para diferentes casos de uso.
O que é PUT em APIs REST?
Para entender a diferença entre PUT e PATCH em APIs REST, primeiro precisamos saber o que é PUT. Baseado em Seção 9.6 RFC 2616, o método PUT na API REST solicita que a entidade incluída seja armazenada no Request-URI fornecido.
Se o Request-URI se referir a um recurso já existente, a entidade incluída DEVE ser considerada como uma versão modificada daquela que reside no servidor de origem. Se o Request-URI não apontar para um recurso existente e esse URI for capaz de ser definido como um novo recurso pelo agente do usuário solicitante, o servidor de origem poderá criar o recurso com esse URI.
Em outras palavras, o método PUT é usado para atualizar um recurso inteiro no servidor. Isso torna o PUT uma atualização mais “completa”, frequentemente utilizada quando é necessária uma substituição completa do recurso.
Portanto, PUT é melhor para os seguintes casos de uso:
- Atualizar um recurso completo (por exemplo, atualizar um perfil de usuário com todas as novas informações).
- Substituindo um item ou registro inteiro.
- Quando a identidade do recurso está clara e seus dados precisam ser totalmente atualizados.
Em sistemas como Elasticsearch, operações idempotentes são necessárias para garantir a consistência dos dados. Por exemplo, atualizar um documento no Elasticsearch usando PUT garante que a mesma solicitação possa ser repetida sem efeitos colaterais indesejados.
O que é PATCH em APIs REST?
Agora que cobrimos PUT em APIs REST, vamos dar uma olhada no que é PATCH em APIs REST e como ele funciona antes de comparar PUT vs PATCH em APIs REST. Conforme definido em RFC 5789, o método PATCH na API REST solicita que um conjunto de alterações descritas na entidade de solicitação seja aplicado ao recurso identificado pelo 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 alterações ao recurso existente sem alterar todo o recurso. Os desenvolvedores geralmente criam patches para representar essas alterações incrementais, garantindo transferência mínima de dados e atualizações eficientes.
É por isso que o método PATCH na API REST é mais adequado para os seguintes casos de uso:
- Atualizar apenas um subconjunto de campos em um recurso (por exemplo, alterar o endereço de e-mail ou número de telefone de um usuário). Um exemplo da API PATCH poderia envolver o envio apenas do novo e-mail, deixando outros campos intactos.
- Melhorando o desempenho minimizando a carga de dados.
- Quando você deseja atualizar um recurso de forma incremental em vez de substituí-lo completamente.
- Crie patches para encapsular alterações de campos específicos, como modificar o e-mail de um usuário, sem afetar dados não relacionados.
Para plataformas como CMS sem cabeça que muitas vezes lidam com estruturas de conteúdo complexas, usar PATCH para atualizações menores — como modificar um único campo — pode reduzir a carga do servidor e melhorar o desempenho.
Com esses dois métodos abordados, você deve ter uma ideia decente do que são PUT e PATCH nas APIs REST. Porém, antes de entrarmos na diferença entre PUT e PATCH em APIs REST, precisamos falar sobre Idempotência nesses dois métodos.
Idempotência em PUT versus patch em APIs REST
Nas APIs REST, idempotência refere-se à propriedade de uma operação que, quando repetida várias vezes com as mesmas entradas, resulta no mesmo resultado. Isso significa que fazer a mesma solicitação várias vezes deverá ter o mesmo efeito no servidor, independentemente de quantas vezes ela for executada. Isto é importante para garantir estabilidade e previsibilidade em uma API. Mas como isso é relevante para a diferença entre PUT e PATCH na API REST?
Método PUT e Idempotência
O método PUT na API REST é sempre idempotente porque foi projetado para substituir todo o recurso em um URI especificado pelos dados fornecidos na solicitação. Em outras palavras, se você executar uma solicitação PUT diversas vezes com os mesmos dados de recurso, o resultado será sempre o mesmo.
Por que PUT é idempotente? Ao fazer uma solicitação PUT, você está essencialmente dizendo ao servidor: “Este é o estado completo e exato que desejo para este recurso”. Quer você emita a solicitaçã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 solicitação PUT várias vezes, o resultado não será alterado porque o recurso será sempre substituído pelos mesmos dados.
Exemplo:
| PUT /users/1{“nome de usuário”: “john_doe”,”e-mail”: “[email protected]”} |
Se você enviar esta solicitação diversas vezes, o resultado será sempre o mesmo:
| {“nome de usuário”: “john_doe”,”e-mail”: “[email protected]”} |
Mesmo que os dados do usuário já sejam esses, enviar novamente a solicitação não altera nada. Ele substitui os dados pelos mesmos dados, de modo que o efeito da solicitação permanece o mesmo, independentemente de quantas vezes ela for repetida. Isso é o que torna o PUT idempotente.
Método PATCH e Idempotência
O método PATCH na API REST, por outro lado, geralmente também é idempotente, mas com mais flexibilidade. Ao criar patches, certifique-se de que as operações sejam idempotentes (por exemplo, definir um valor) para evitar efeitos colaterais indesejados de solicitações repetidas. Se o PATCH é idempotente depende da operação e dos dados que estão sendo modificados.
Por que o PATCH é idempotente? Para solicitações PATCH, idempotência significa que aplicar o mesmo patch diversas vezes terá o mesmo resultado. Isto é verdade desde que o adesivo em si não cause efeitos colaterais ou alterações adicionais quando aplicado repetidamente. Se você continuar aplicando o mesmo patch com os mesmos dados, o resultado deverá permanecer inalterado após a primeira aplicação.
Por exemplo, se você estiver apenas atualizando o e-mail de um usuário, enviar repetidamente a mesma solicitação PATCH não alterará o resultado após a primeira vez, mesmo que a solicitação seja feita várias vezes. O email do usuário permanecerá o mesmo e o estado do recurso não será alterado.
Exemplo de API PATCH:
| PATCH /users/1{“email”: “[email protected]”} |
Se o e-mail já era [email protected], aplicar este PATCH novamente não resultará em nenhuma alteração, tornando-o idempotente.
No entanto, PATCH também pode ser não idempotente em alguns casos. Por exemplo, se uma operação PATCH modificar um contador ou adicionar itens a uma lista (como incrementar um número ou anexar a uma matriz), aplicações repetidas do mesmo PATCH poderão levar a resultados diferentes. Isso violaria a propriedade de idempotência.
Exemplo de API REST PATCH não idempotente:
| PATCH /counter/1{“incremento”: 1} |
Se você aplicar este PATCH repetidamente, o contador continuará aumentando, resultando em valores diferentes a cada vez. Isto não é idempotente porque o resultado muda com cada aplicação.
Agora que você conhece o essencial, podemos ver alguns exemplos de cenários para entender melhor a diferença entre PUT e PATCH em APIs REST.
Cenários de exemplo: PUT vs PATCH em APIs REST
Deixando a teoria de lado, vamos dar uma olhada na diferença entre PUT e PATCH com exemplos, incluindo operações idempotentes e não idempotentes.
Cenário 1: Solicitação PUT – Substituindo um recurso inteiro
Imagine um endpoint de API para gerenciamento de produtos em um sistema de comércio eletrônico. Você precisa atualizar todos os detalhes de um produto, incluindo nome, preço e descrição. Este é um exemplo típico do método HTTP PUT vs PATCH, onde PUT é usado para substituir o recurso completo do produto.
Produto inicial:
| GET /products/1001{“id”: 1001,”nome”: “Laptop”,”preço”: 999,99,”descrição”: “Um laptop poderoso.”} |
Você deseja atualizar o preço e a descrição do produto. Você envia uma solicitação PUT com todo o recurso:
Solicitação COLOCAR:
| PUT /products/1001{“id”: 1001,”nome”: “Laptop”,”preço”: 899,99,”descrição”: “Um laptop poderoso com desconto.”} |
Se você fizer essa 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á todas as vezes. Isso garante a natureza idempotente do PUT.
Resultado (após solicitação PUT):
| {“id”: 1001,”nome”: “Laptop”,”preço”: 899,99,”descrição”: “Um laptop poderoso com desconto.”} |
Cenário 2: Solicitação PATCH – Atualizando Parte de um Recurso
Agora, vamos considerar uma solicitação PATCH para atualizar apenas parte dos detalhes do produto, como a descrição. Exemplo de API PATCH: Se você deseja 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 requerem modificação, como a descrição neste exemplo API REST PATCH.
Produto inicial:
| GET /products/1001{“id”: 1001,”nome”: “Laptop”,”preço”: 999,99,”descrição”: “Um laptop poderoso.”} |
Solicitação de patch:
| PATCH /products/1001{“descrição”: “Um laptop leve e poderoso.”} |
Ao enviar 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 de PATCH):
| {“id”: 1001,”nome”: “Laptop”,”preço”: 999,99,”descrição”: “Um laptop leve e poderoso.”} |
Se você aplicar o mesmo PATCH novamente, a descrição do produto ainda será a mesma que era 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
Vejamos uma operação PATCH não idempotente. Suponha que haja um ponto final para o saldo da carteira de um usuário e você queira aumentar o saldo. Um exemplo de diferença entre PUT e PATCH pode ser ilustrado aqui: PATCH adicionará um valor ao saldo cada vez
Carteira Inicial:
| GET /users/1/wallet{“id”: 1,”saldo”: 100,00} |
Solicitação de patch:
| PATCH /users/1/wallet{“incremento”: 50,00} |
Esta solicitação PATCH aumentará o saldo da carteira em US$ 50. Se você enviar esta solicitação PATCH várias vezes, o saldo continuará aumentando a cada PATCH, levando a um resultado diferente a cada vez. Isso não é idempotente porque aplicar o mesmo PATCH repetidamente causará um resultado diferente.
Resultado (após a primeira solicitação de PATCH):
| {“id”: 1,”saldo”: 150,00} |
Resultado (após a segunda solicitação de PATCH):
| {“id”: 1,”saldo”: 200,00} |
Aqui, PATCH não é idempotente porque solicitações repetidas com os mesmos dados produzem resultados diferentes.
Recapitulação: principais diferenças entre PUT e PATCH em APIs REST
A principal diferença entre PUT e PATCH na API REST é como eles lidam com atualizações. PUT substitui todo o recurso, portanto, todos os campos ausentes são eliminados, o que pode levar à perda de dados. É por isso que os desenvolvedores criam patches para atualizações parciais — para evitar a substituição de campos inalterados e manter a integridade dos dados.
Isso torna o PATCH mais eficiente para atualizações parciais. Um exemplo da API PATCH é que se você deseja atualizar apenas o e-mail de um usuário, a criação de patches enviaria apenas o campo de e-mail, ao contrário de uma solicitação PUT que exigiria todos os dados do usuário.
Com PUT, a carga completa de dados é necessária. Isso significa que todos os campos devem ser enviados e todos os campos ausentes serão apagados. O PATCH, porém, envia apenas os campos que precisam ser atualizados, tornando-o mais eficiente, principalmente para grandes recursos com alterações mínimas. O método PATCH na API REST permite solicitações menores e mais focadas, 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 porque substitui todo o recurso. 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 incrementar um contador, solicitações repetidas poderão levar a resultados diferentes. No entanto, as operações da API PATCH também podem ser projetadas para serem idempotentes.
Concluindo, a diferença entre PUT e PATCH na API REST se resume à natureza das atualizações: PATCH é para alterações parciais, enquanto PUT é para substituição completa de recursos. Ambos são idempotentes, mas PATCH pode ser mais complexo.
Considerações Finais
Tanto PUT quanto PATCH são métodos HTTP fundamentais no design da API REST, mas servem a propósitos diferentes, que é a essência da diferença entre PUT e PATCH na API REST. Você pode melhorar significativamente a eficiência, a clareza e a funcionalidade da sua API entendendo a diferença entre PUT e PATCH com os exemplos abordados anteriormente neste artigo. Ao escolher o método correto (PATCH versus atualização REST) com base no seu caso de uso, você pode tornar sua API mais eficiente, fácil de manter e fácil de usar. Sempre considere a natureza da atualização (seja ela total ou parcial), juntamente com o impacto no desempenho e na integridade dos dados, e selecione o método que melhor se alinha às suas necessidades.
