Blog

JSON Patch: A Maneira Inteligente de Atualizar seus Dados de API

INEZA Felin-Michel

INEZA Felin-Michel

1 setembro 2025

JSON Patch: A Maneira Inteligente de Atualizar seus Dados de API

Você construiu uma API moderna. O GET busca dados, o POST cria novos recursos — tudo tranquilo até agora. Mas quando se trata de atualizar dados, as coisas ficam complicadas.

Digamos que um usuário queira apenas mudar seu e-mail. Você realmente precisa que ele reenvie o perfil de usuário inteiro? Isso é desajeitado, ineficiente e propenso a erros — especialmente com conexões lentas ou atualizações conflitantes.

Existe uma maneira melhor: JSON Patch.
Em vez de enviar o objeto inteiro, você envia apenas as alterações. Pense nisso como dar a um alfaiate uma lista de ajustes em vez de refazer o terno inteiro.

Como JSON se tornou a linguagem universal para APIs, JSON Patch oferece uma solução leve e elegante para atualizações parciais.

Claro, projetar e testar APIs com JSON Patch requer as ferramentas certas. É aí que o Apidog entra. Ele permite que você crie, teste e valide requisições JSON Patch com facilidade — para que você saiba que suas atualizações funcionam como esperado antes de escrever uma única linha de código. O melhor de tudo é que é gratuito para baixar e começar a experimentar hoje mesmo.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e completa para sua Equipe de Desenvolvedores trabalharem juntos com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!
botão

A seguir, vamos detalhar o que é JSON Patch, como funciona e por que ele deve fazer parte do seu próximo projeto.

O Problema: A Requisição PUT "Cega"

Para entender por que JSON Patch é tão útil, primeiro precisamos entender o problema que ele resolve. Tradicionalmente, a atualização de um recurso em uma API RESTful é feita com o método HTTP PUT.

Uma requisição PUT é feita para ser idempotente (fazer a mesma requisição várias vezes tem o mesmo efeito que fazê-la uma vez) e ela tipicamente substitui o recurso inteiro na URL de destino pela nova representação fornecida no corpo da requisição.

Vamos imaginar um recurso de perfil de usuário:

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Agora, se John quiser apenas mudar seu endereço de e-mail, uma requisição PUT típica seria assim:

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // O campo alterado
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Você vê o problema? Tivemos que enviar de volta cada campo, mesmo que 99% dos dados não tivessem mudado. Essa abordagem tem várias desvantagens:

  1. Aumento da Largura de Banda: Estamos enviando muitos dados desnecessários pela rede. Para recursos grandes, isso pode ser um impacto significativo no desempenho, especialmente em redes móveis.
  2. Maior Risco de Conflitos: Se outro processo atualizar o campo age enquanto John estiver editando seu email, a requisição PUT de John poderia acidentalmente sobrescrever aquela nova idade com o valor antigo que ele enviou.
  3. Complexidade para o Cliente: A aplicação cliente deve primeiro fazer um GET do recurso inteiro, modificar o campo específico e, em seguida, fazer um PUT de tudo de volta. São várias etapas e exige que o cliente gerencie todo o estado.

É aqui que o método HTTP PATCH entra em ação.

A Solução: Apresentando HTTP PATCH e JSON Patch

O método HTTP PATCH foi introduzido para permitir modificações parciais em um recurso. Ao contrário do PUT, que substitui o recurso inteiro, o PATCH aplica um conjunto de alterações ao recurso.

Mas há um porém: o padrão HTTP não define qual deve ser o formato dessas "alterações". Você poderia inventar o seu próprio. Você poderia enviar algo como:

{ "op": "change_email", "value": "new@example.com" }

Mas isso seria personalizado, não-padrão, e outros desenvolvedores teriam que aprender sua linguagem específica.

É essa lacuna que o JSON Patch preenche. JSON Patch (definido na RFC 6902) é um formato padronizado para especificar alterações a serem aplicadas a um documento JSON. Ele fornece uma linguagem clara e inequívoca para descrever exatamente como um documento JSON deve ser modificado.

Quando você combina o método HTTP PATCH com um corpo formatado como um documento JSON Patch, você tem uma maneira poderosa e baseada em padrões para realizar atualizações parciais.

Como o JSON Patch Funciona: O Básico

Um documento JSON Patch é sempre um array JSON. Cada elemento no array é um objeto de operação. Essas operações são aplicadas ao documento de destino em ordem, e o patch inteiro é atômico, o que significa que se qualquer operação falhar, o patch inteiro é abortado e o documento permanece inalterado.

Cada objeto de operação tem um membro obrigatório op (abreviação de "operation") que especifica a ação a ser executada. As operações mais comuns são add, remove, replace, move e copy.

Vamos ver o exemplo anterior de John mudando seu e-mail. Usando JSON Patch, a requisição se torna dramaticamente mais simples:

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

É isso! Estamos enviando uma única operação: "substituir o valor no caminho '/email' por este novo valor." A requisição é pequena, clara e orientada pela intenção. Não tocamos em nenhum outro campo.

Entendendo a Propriedade path

A propriedade path é um JSON Pointer (RFC 6901), uma string que usa uma sintaxe baseada em barras para navegar através do documento JSON até o valor específico que você deseja manipular.

Essa sintaxe é poderosa para navegar em estruturas JSON aninhadas.

JSON Patch vs JSON Merge Patch

Desenvolvedores frequentemente confundem JSON Patch (RFC 6902) com JSON Merge Patch (RFC 7386). Vamos esclarecer.

JSON Patch:

JSON Merge Patch:

Em resumo:

As Operações JSON Patch

Vamos detalhar as operações mais comuns com exemplos. Usaremos o mesmo perfil de usuário como nosso documento de destino.

1. A Operação add

A operação add é usada para inserir um novo valor em um objeto ou array.

Adicionar uma nova propriedade a um objeto:

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

Isso adiciona um novo campo twitterHandle ao objeto de usuário.

Adicionar um elemento a um array (em um índice específico):

Imagine que o usuário tem um array "hobbies": ["reading", "cycling"].

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

Isso insere "hiking" no índice 1, resultando em ["reading", "hiking", "cycling"]. Para adicionar ao final do array, você pode usar /-: { "op": "add", "path": "/hobbies/-", "value": "hiking" }.

2. A Operação remove

A operação remove exclui um valor em um local especificado.

Remover uma propriedade de um objeto:

{ "op": "remove", "path": "/age" }

Isso remove todo o campo age do objeto de usuário.

Remover um elemento de um array:

{ "op": "remove", "path": "/hobbies/0" }

Isso remove o primeiro elemento (índice 0) do array hobbies.

3. A Operação replace

A operação replace é essencialmente uma combinação de remove e add no mesmo caminho. Ela substitui o valor existente em um local por um novo valor. Nosso exemplo de e-mail foi um replace clássico.

Mudar a preferência de tema de um usuário:

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. A Operação move

A operação move remove um valor de um local e o adiciona a outro.

Mover um valor de uma propriedade para outra:

{ "op": "move", "from": "/firstName", "path": "/first_name" }

Isso moveria o valor de firstName para uma nova propriedade chamada first_name e removeria a propriedade antiga firstName.

5. A Operação copy

A operação copy copia um valor de um local para outro. O valor original permanece inalterado.

Criar um backup de uma configuração:

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

Isso copia o valor do tema atual para um novo campo backupTheme.

6. A Operação test

Esta é uma funcionalidade de segurança. A operação test verifica se um valor em um local é igual a um valor especificado. Se o teste falhar, o patch inteiro é abortado. Isso é incrivelmente útil para prevenir conflitos (bloqueio otimista).

Garantir que ninguém mais mudou o e-mail antes de atualizá-lo:

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

Se o email atual não for "john.old@example.com" (talvez outro processo já o tenha alterado), a operação test falha, e o replace nunca acontece. Isso garante que sua atualização seja baseada no último estado conhecido.

Por Que Usar JSON Patch? Os Benefícios

  1. Eficiência: O benefício mais óbvio. Você envia apenas as alterações, reduzindo significativamente o tamanho da carga útil e melhorando o desempenho.
  2. Controle de Concorrência: A operação test fornece um mecanismo embutido para bloqueio otimista, ajudando a evitar atualizações perdidas e condições de corrida.
  3. Atomicidade: A natureza de tudo ou nada de uma aplicação de patch garante que seus dados permaneçam consistentes. Se a quinta operação em um patch de dez operações falhar, as quatro primeiras são revertidas.
  4. Clareza e Intenção: O corpo da requisição descreve claramente a intenção da mudança ("substituir o e-mail", "adicionar um hobby") em vez de apenas despejar um novo estado. Isso torna os logs mais legíveis e a depuração mais fácil.
  5. Padronização: É um padrão IETF (RFC 6902). Outros desenvolvedores o reconhecerão, e muitas bibliotecas e frameworks em diferentes linguagens de programação têm suporte embutido para analisar e aplicar documentos JSON Patch.

Armadilhas Comuns e Erros com JSON Patch

Embora JSON Patch seja poderoso, desenvolvedores frequentemente encontram esses problemas:

Por Que APIs Usam JSON Patch

APIs adoram JSON Patch porque é:

Por exemplo, a API do GitHub suporta JSON Patch para editar metadados de repositório de forma eficiente.

JSON Patch em APIs REST

Em APIs RESTful, JSON Patch é frequentemente usado com o método HTTP PATCH.

PATCH vs PUT:

Com JSON Patch, o Content-Type é:

application/json-patch+json

Isso informa ao servidor que o corpo contém um documento JSON Patch.

JSON Patch em GraphQL e Outros Protocolos

Embora JSON Patch seja principalmente usado em APIs REST, ele também tem relevância em:

Como JSON Patch Melhora a Eficiência

Imagine um aplicativo móvel sincronizando perfis de usuário. Em vez de reenviar um arquivo JSON de 2MB para cada pequena atualização, o aplicativo pode simplesmente enviar uma pequena requisição de patch.

Isso significa:

Desafios e Considerações

JSON Patch é poderoso, mas não está isento de suas complexidades.

  1. Implementação Complexa no Servidor: Aplicar um patch corretamente no servidor é mais complexo do que simplesmente aceitar um novo objeto JSON. Você precisa validar cada operação, lidar com ponteiros para caminhos inexistentes de forma apropriada e garantir que toda a sequência seja aplicada atomicamente. Felizmente, a maioria dos frameworks web modernos possui bibliotecas para lidar com isso para você (por exemplo, json-patch para Node.js, jsonpatch para Python, JsonPatchDocument em .NET).
  2. Potencial para Erros: Um documento de patch malformado ou um ponteiro inválido (por exemplo, tentar replace um campo que não existe) resultará em um erro. Sua API deve lidar com isso graciosamente e retornar mensagens de erro claras (geralmente um 422 Unprocessable Entity ou 400 Bad Request).
  3. Não é uma Bala de Prata: Para recursos muito simples, um PUT ainda pode ser mais simples. JSON Patch brilha quando seus recursos são grandes ou quando você precisa suportar atualizações complexas e condicionais.

Testando Endpoint JSON Patch com Apidog

Testar JSON Patch manualmente pode ser frustrante. É aqui que uma ferramenta de API sofisticada se torna inestimável. O Apidog, uma plataforma de desenvolvimento de API tudo-em-um, pode ser uma grande ajuda aqui:

botão

Exemplo de fluxo de trabalho no Apidog:

  1. Crie uma nova requisição.
  2. Defina o método como PATCH.
  3. Adicione Content-Type: application/json-patch+json.
  4. Insira seu array JSON Patch.
  5. Envie e verifique os resultados instantaneamente.

Ao usar o Apidog, você passa de adivinhar se seu patch está correto para saber que ele foi construído corretamente, permitindo que você implemente e consuma APIs JSON Patch com confiança e comece a testar JSON Patch como um profissional.

Melhores Práticas de JSON Patch

Para usar JSON Patch de forma eficaz:

  1. Valide seus documentos JSON Patch antes de enviar.
  2. Use operações de teste quando a consistência for importante.
  3. Mantenha os patches pequenos para eficiência.
  4. Documente sua API claramente ao usar JSON Patch.
  5. Use ferramentas como Apidog para otimizar os testes.

Conclusão: Abraçando um Padrão de API Mais Eficiente

Então, o que é JSON Patch?

É uma forma padronizada de descrever alterações em documentos JSON usando operações como adicionar, remover e substituir. Em vez de enviar objetos completos, você pode enviar apenas as alterações, tornando suas APIs mais eficientes, confiáveis e flexíveis.

JSON Patch transforma a maneira como pensamos sobre a atualização de dados via APIs. Ele nos move do instrumento bruto da substituição de documentos completos para a precisão das mudanças cirúrgicas. Ao abraçar este padrão, construímos APIs que são mais eficientes, menos propensas a conflitos e mais claras em sua intenção.

Embora exija um pouco mais de planejamento inicial no lado do servidor, os benefícios para as aplicações cliente e o desempenho da rede são substanciais. Da próxima vez que você se encontrar projetando um endpoint de atualização, resista ao PUT padrão e pergunte a si mesmo: "Isso poderia ser um trabalho para PATCH?"

Para desenvolvedores, entender JSON Patch é fundamental para trabalhar com APIs modernas, especialmente ao lidar com atualizações parciais. E com ferramentas como o Apidog, você pode testar, validar e depurar requisições JSON Patch com facilidade.

botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar