Patch verbo - Patch verb
Na computação, o método PATCH é um método de solicitação suportado pelo protocolo Hypertext Transfer Protocol (HTTP) para fazer alterações parciais em um recurso existente. O método PATCH fornece uma entidade que contém uma lista de alterações a serem aplicadas ao recurso solicitado usando o HTTP Uniform Resource Identifier (URI). A lista de alterações é fornecida na forma de um documento PATCH. Se o recurso solicitado não existir, o servidor pode criar o recurso dependendo do tipo de mídia e das permissões do documento PATCH . As alterações descritas no documento PATCH devem ser bem definidas semanticamente, mas podem ter um tipo de mídia diferente do recurso que está sendo corrigido. Frameworks como XML , JSON podem ser usados para descrever as mudanças no documento PATCH.
História do PATCH
De acordo com a semântica definida no protocolo HTTP , os métodos GET , PUT e POST precisam usar uma representação completa do recurso. O método PUT que pode ser usado para criação ou substituição de recursos é idempotente e pode ser usado apenas para atualizações completas. Os formulários de edição usados no aplicativo Ruby on Rails convencional precisam criar novos recursos aplicando atualizações parciais a um recurso pai. Devido a esse requisito, o método PATCH foi adicionado ao protocolo HTTP em 2010.
PUT vs PATCH vs POST
HTTP é a base da comunicação de dados para a World Wide Web . É um protocolo de solicitação-resposta que ajuda os usuários a se comunicarem com o servidor para realizar operações CRUD . O HTTP oferece suporte a vários métodos de solicitação, como PUT , POST e PATCH, para criar ou atualizar recursos.
A principal diferença entre os métodos PUT e PATCH é que o método PUT usa o URI de solicitação para fornecer uma versão modificada do recurso solicitado que substitui a versão original do recurso, enquanto o método PATCH fornece um conjunto de instruções para modificar o recurso. Se o documento PATCH for maior que o tamanho da nova versão do recurso enviado pelo método PUT , o método PUT é o preferido.
O método POST pode ser usado para enviar atualizações parciais para um recurso. A principal diferença entre os métodos POST e PATCH é que o método POST só pode ser usado quando é escrito para suportar os aplicativos ou os aplicativos suportam sua semântica, enquanto o método PATCH pode ser usado de forma genérica e não requer suporte de aplicativos. Se o resultado do uso do método PATCH não for conhecido, o método POST é o preferido.
Recursos de patch
O método PATCH é atômico . Todas as alterações especificadas pelo método PATCH são aplicadas ou nenhuma das alterações é aplicada pelo servidor. Existem muitas maneiras de verificar se um patch foi aplicado com sucesso. Por exemplo, o utilitário 'diff' pode ser aplicado à versão mais antiga e à versão mais recente de um arquivo para encontrar as diferenças entre elas.
Uma resposta PATCH em cache é considerada obsoleta. Ele só pode ser usado para as solicitações GET e HEAD que podem seguir a solicitação PATCH.
Os cabeçalhos de entidade no documento PATCH são aplicáveis apenas ao documento PATCH e não podem ser aplicados ao recurso solicitado.
Não existe um formato padrão para o documento PATCH e é diferente para diferentes tipos de recursos. O servidor deve verificar se o documento PATCH recebido é apropriado para o recurso solicitado.
Um documento de patch JSON seria semelhante a
{ "op": "add", "path": "/count", "value": 1 }
"op" representa a operação realizada no recurso. "path" representa o recurso que está sendo modificado. "valor" representa a quantidade que está sendo adicionada ao recurso existente. Antes de aplicar as alterações no documento PATCH, o servidor deve verificar se o documento PATCH recebido é adequado para o recurso solicitado. Se a solicitação PATCH for bem-sucedida, ele retornará uma resposta 204 .
Um documento XML PATCH pareceria
<add sel="doc/user[@email='xyz@abc.com']" type="@address">
ABC Road
</add>
O elemento <user> está localizado usando o atributo 'email'. Um novo atributo 'endereço' com o valor "ABC Road" é adicionado ao elemento <user>.
Exemplo
Um exemplo de solicitação PATCH simples
PATCH /example.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120
[changes]
[alterações] é o documento de patch contendo todas as alterações que precisam ser feitas no recurso example.txt
Resposta PATCH bem-sucedida para o arquivo de texto existente:
HTTP/1.1 204 No Content Content-Location: /example.txt ETag: "c0b42b66f"
A resposta 204 significa que a solicitação foi processada com sucesso.
Trade-offs entre PUT e PATCH
Usar o método PUT consome mais largura de banda em comparação com o método PATCH quando apenas algumas alterações precisam ser aplicadas a um recurso. Mas quando o método PATCH é usado, geralmente envolve buscar o recurso do servidor, comparando o arquivo original com os novos, criando e enviando um arquivo diff. No lado do servidor, o servidor deve ler o arquivo diff e fazer as modificações. Isso envolve muita sobrecarga em comparação com o método PUT. Por outro lado, o método PUT requer que um GET seja executado antes do PUT e é difícil garantir que o recurso não seja modificado entre as solicitações GET e PUT .
Cuidado
O método PATCH não é "seguro" no sentido do RFC 2616: ele pode modificar recursos, não necessariamente limitados aos mencionados no URI .
O método PATCH não é idempotente . Ele pode ser tornado idempotente usando uma solicitação condicional. Quando um cliente faz uma solicitação condicional a um recurso, a solicitação é bem-sucedida apenas se o recurso não tiver sido atualizado desde o último acesso do cliente a esse recurso. Isso também ajuda a evitar a corrupção do recurso, pois algumas atualizações em um recurso só podem ser executadas a partir de um determinado ponto de base.
Manipulação de erros
Uma solicitação PATCH pode falhar se algum dos seguintes erros ocorrer:
Documento de patch malformado
O servidor retorna uma resposta 400 (solicitação incorreta) se o documento PATCH não for formatado conforme necessário.
Documento de patch não suportado
O servidor retorna uma resposta 415 ( Tipo de mídia não suportado ) com um cabeçalho de resposta Aceitar Patch contendo os tipos de mídia suportados quando o cliente envia um documento de patch não suportado. Isso informa ao cliente que o documento PATCH enviado pelo cliente não pode ser aplicado ao recurso solicitado.
Pedido não processável
O servidor retorna uma resposta 422 (Unprocessable Entity) quando o servidor entende o documento PATCH, mas não pode modificar o recurso solicitado porque isso faz com que o recurso se torne inválido ou resulta em algum outro estado de erro.
Recurso não encontrado
O servidor retorna uma resposta 404 (não encontrado) quando o documento PATCH não pode ser aplicado a um recurso inexistente.
Estado conflitante
O servidor retorna uma resposta 409 (Conflito) quando o servidor não pode aplicar um patch para o estado atual do recurso.
Modificação conflitante
O servidor retorna uma resposta 412 (Precondition Failed) quando a pré-condição fornecida pelo cliente usando o cabeçalho If-Match ou If-Unmodified-Since falha. Se nenhuma condição prévia for fornecida e houver uma modificação conflitante, o servidor retornará uma resposta 409 (Conflito).
Modificação simultânea
O servidor retorna uma resposta 409 (Conflito) se as solicitações PATCH para um determinado recurso precisam ser aplicadas em uma determinada ordem e o servidor não é capaz de lidar com solicitações PATCH simultâneas.
Considerações de segurança
A solicitação PATCH precisa usar mecanismos como solicitações condicionais usando Etags e o cabeçalho de solicitação If-Match para garantir que os dados não sejam corrompidos durante o patch. Em caso de falha de uma solicitação PATCH ou falha do canal ou tempo limite, o cliente pode usar uma solicitação GET para verificar o estado do recurso. O servidor deve garantir que clientes mal-intencionados não usem o método PATCH para consumir recursos excessivos do servidor.