Aproveitando o poder do JSON Patch

 (zuplo.com)
15 pontos por GN⁺ 2024-10-20 | 1 comentários | Compartilhar no WhatsApp
  • JSON Patch é um formato padrão definido na RFC 6902 para modificar documentos JSON
    • Ele oferece uma forma simples e eficiente de atualizar recursos parcialmente via HTTP
    • Enquanto os métodos PUT e POST exigiam o envio de todos os dados, o método PATCH permite atualizações parciais
  • JSON Patch fornece uma forma clara e concisa de expressar mudanças em documentos JSON, reduzindo o uso de largura de banda e melhorando o desempenho de aplicações web

Como o JSON Patch funciona

  • JSON Patch funciona como uma série de operações atômicas sobre um documento JSON.
  • Cada operação inclui os campos op e path, que executam uma ação em uma posição específica do documento.
  • Por exemplo, a operação add adiciona um novo campo, e a operação replace substitui um campo existente.

JSON Pointer

  • JSON Patch usa JSON Pointer para identificar partes específicas do documento.
  • JSON Pointer é uma sequência de tokens separada por barras (/) que identifica a estrutura hierárquica do documento.
  • Por exemplo, /user/name identifica o campo name dentro do objeto user.

Vantagens e desvantagens do JSON Patch

Vantagens

  1. Precisão: permite modificar com exatidão elementos específicos em estruturas complexas.
  2. Eficiência: envia apenas as alterações, minimizando o volume de dados transferidos e a latência.
  3. Atomicidade: em caso de falha, é possível reverter toda a operação.
  4. Idempotência: permite tentativas seguras de repetição.
  5. Operações complexas: é possível mover ou copiar elementos.
  6. Validação: a API pode validar os patches recebidos para reduzir requisições inválidas.
  7. Baseado em padrão: facilita a integração com diversos clientes e servidores.
  8. Controle de acesso em nível de campo: permite restringir modificações com granularidade fina.
  9. Operações em lote: permite processar várias mudanças em uma única requisição.

Desvantagens

  1. Complexidade: pode ser difícil lidar com estruturas JSON complexas.
  2. Custo de manutenção: à medida que a API evolui, os caminhos podem se tornar inválidos.
  3. Dificuldade de depuração: quando várias operações são agrupadas, o rastreamento pode ficar difícil.
  4. Preservação da ordem de objetos: operações de movimentação não garantem a ordem dos objetos.
  5. Problemas de segurança: o tratamento inadequado de requisições pode gerar vulnerabilidades.

Exemplos de operações do JSON Patch

  • Add: adiciona um novo campo.
  • Remove: remove um campo existente.
  • Replace: substitui um campo existente por um novo valor.
  • Move: move um elemento para outra posição.
  • Copy: copia um elemento para outra posição.
  • Test: testa se um valor está definido em um caminho específico.

JSON Patch em ferramentas e bibliotecas

  • Existem bibliotecas com suporte a JSON Patch em várias linguagens de programação: fast-json-patch, python-json-patch, JsonPatch library in .NET etc.
  • Uma excelente ferramenta para aprender JSON Patch é o jsonpatch.me, um serviço online gratuito para executar comandos de JSON Patch. Também possui API

Resumo do GN⁺

  • JSON Patch é uma ferramenta poderosa para realizar atualizações parciais de documentos JSON com eficiência.
  • Embora possa haver dificuldades ao lidar com estruturas JSON complexas, isso pode ser superado com diversas bibliotecas e ferramentas.
  • JSON Patch é útil para reduzir o volume de dados transferidos e melhorar o desempenho de aplicações web.
  • Alternativas como JSON Merge Patch também podem ser consideradas, e o uso de JSON Patch no desenvolvimento de APIs pode aumentar a eficiência.

Leituras relacionadas

1 comentários

 
GN⁺ 2024-10-20
Comentários do Hacker News

  • O JSON Patch foi projetado para modificar qualquer documento JSON, então parece complexo. Se você restringir um pouco o conjunto de dados, dá para aplicar patches nos documentos de forma bem mais simples. Por exemplo, no Firebase não é possível armazenar valores null, e definir algo como null significa remover. Esse tipo de restrição simples permite implementar PATCH com facilidade. O fato de não haver nada novo para aprender além de que "null significa exclusão" é uma ótima característica da API.

  • Usar / como separador no JSON é uma escolha estranha. Como JSON é um subconjunto de JS, eu esperaria . como separador. Quando vejo /, parece uma especificação escrita por pessoal de backend, tentando transformar o caminho em URL para resolver ambiguidades entre caminhos relativos e absolutos.

  • Acho que o caminho deveria ser um array, não uma string. Caso contrário, é preciso escapar / nas chaves e fazer parsing da string de caminho. Isso impede o tratamento de documentos JSON arbitrários.

  • Já usei JSON Patch uma vez, como um hack para resolver rapidamente um problema inesperado. Tínhamos criado uma interface web para contratados no exterior anotarem dados de texto no nível das palavras. Os dados deveriam ser anotados em pequenos trechos, mas acabaram sendo atribuídos ao documento inteiro, então as anotações não eram salvas. Descobri o JSON Patch e modifiquei o código de upload para usar apenas patches.

  • No modo como o JSON Patch especifica caminhos, falta uma sintaxe padrão que permita selecionar itens de um array por pares identificadores de chave-valor, em vez de pelo índice. Isso é especialmente importante ao adicionar itens ou ao analisar diferenças entre itens JSON de versões anteriores.

  • Uma das forças do JSON Patch é a idempotência. As operações de JSON Patch podem ser repetidas com segurança, sem efeitos colaterais indesejados. Mas me surpreendeu o fato de não ser possível adicionar itens a um array.

  • Funciona de forma parecida com as consultas de atualização do MongoDB. Fico curioso se existe alguma forma de usar essa linguagem de atualização em arquivos locais sem precisar rodar o MongoDB inteiro.

  • Seria preciso comparar JSONDiffpatch e JSON Patch. O JSONDiffpatch funciona bem no navegador e também em Node/Cloudflare Workers.

  • Tive dificuldade para convencer parceiros externos a aprender JSON Patch. Usei isso em uma API voltada para clientes, e exigiu bastante esforço para que os usuários entendessem e adotassem.

  • A especificação JSON Pointer parece meio "URL-like", então dá a impressão de que seria possível pular a sintaxe meta-JSON. test e copy são elementos próprios da especificação do JSON Patch, e também é possível fazer uma "transação" executando várias edições de uma só vez.