Resumo

  • Accept-Patch lista os tipos de mídia aceitos como documentos de patch. Sua presença indica capacidade PATCH no recurso, mas não autentica o solicitante, concede acesso, escolhe o formato nem valida uma mudança concreta.
  • Descoberta, linguagem do documento, precondição de estado e autorização são decisões independentes. O campo prepara uma possível requisição; as demais só podem ser tomadas quando essa requisição chega em seu contexto real.

Uma resposta OPTIONS apresenta application/json-patch+json e application/merge-patch+json. O cliente aprendeu que o recurso anuncia duas gramáticas. Não aprendeu se sua conta pode escrever, se a versão lida continua atual ou se a operação respeita as regras de negócio. Não recebeu uma credencial.

O erro comum é transformar um anúncio formal em um único sinal chamado “editável”. Accept-Patch vem do servidor, tem registro permanente e costuma aparecer ao lado de Allow. Mesmo assim, a RFC 5789 define a publicidade de formatos e, separadamente, exige autorização para as requisições.

Capacidade do recurso não é direito do usuário

PATCH foi padronizado porque PUT representa substituição completa, enquanto uma mudança parcial precisa de instruções cuja semântica é definida por um tipo de mídia. A URI-alvo identifica o recurso. Content-Type identifica a linguagem. Uma precondição liga o pedido a um estado observado. Autenticação e controle de acesso decidem se o principal pode agir.

Accept-Patch vem antes dessas decisões. Seu valor é uma lista de tipos de mídia, com parâmetros opcionais. Ele deve aparecer em OPTIONS para recursos que suportam PATCH. Quando aparece em resposta a qualquer método, indica implicitamente que PATCH é permitido como capacidade do recurso; cada tipo listado é anunciado como aceito ali.

“Permitido” tem escopo técnico. A seção de segurança da RFC 5789 trata autorização, controle de acesso e autenticação como deveres separados. Assim, um GET público pode anunciar formatos enquanto um PATCH anônimo recebe 401 ou 403. Contas diferentes podem ver a mesma lista e ter limites de campos diferentes.

PATCH pode estar em Allow sem Accept-Patch; nesse caso, o método é anunciado, mas os formatos não. RFC 9110 também diz que o conjunto efetivo de métodos é determinado pelo origin a cada requisição e pode mudar. Descoberta é observação datada, não reserva.

O tipo de mídia define o programa

Não existe formato PATCH padrão obrigatório. O servidor precisa verificar se o documento é adequado ao alvo. O Erratum 3169, verificado, reforça que a semântica vem do tipo de mídia. Entender application/json ou application/xml não autoriza o servidor a inventar uma linguagem de patch privada.

JSON Patch usa application/json-patch+json e uma sequência de operações como add, remove, replace, move, copy e test. JSON Merge Patch usa application/merge-patch+json, imita a forma do alvo, compara membros e reserva null para remoção.

Ambos tratam JSON, porém não são equivalentes. test pode proteger uma hipótese pontual em JSON Patch. Merge Patch é conciso para objetos, mas não serve bem quando null é valor real ou quando arrays exigem edição detalhada. Listar os dois não autoriza conversão automática nem estabelece preferência pela ordem.

O cliente escolhe conscientemente e declara Content-Type. Trocar apenas o rótulo de um corpo já construído não muda sua gramática.

Um anúncio pode acompanhar a recusa

Formato anunciado não é promessa de sucesso. Um documento malformado pode gerar 400; tipo não suportado, 415; instruções válidas mas inexequíveis, 422; alvo ausente incompatível, 404; conflito de estado ou concorrência, 409; precondição falha, 412.

A resposta 415 deve incluir Accept-Patch com alternativas. O servidor recusa a tentativa e fornece informação para outra decisão. O campo não aceita o pedido retroativamente, não permite mudar só Content-Type e não garante que outro documento passe por autorização e regras de negócio.

O cliente pode preservar a falha, mostrar as opções e decidir se consegue construir uma nova operação equivalente. Será outra requisição, avaliada em outro momento. Descoberta reduz adivinhação; não obriga repetição.

If-Match protege versão, não privilégio

Patches que dependem de uma base conhecida podem corromper estado sob concorrência. A RFC 5789 recomenda requisições condicionais e cita um ETag forte em If-Match.

A RFC 9110 manda avaliar If-Match antes do método, usando comparação forte. Se o estado já mudou, 412 evita que o servidor improvise uma rebase. Mas ETag não é segredo nem autorização: alguém sem direito pode conhecer o valor atual, e alguém autorizado pode enviar um valor antigo.

IANA registra PATCH como não seguro e não idempotente. Uma requisição específica pode ser construída de modo idempotente, mas isso depende das operações. Accept-Patch não descreve o efeito de repetir o documento futuro.

Atomicidade pertence à execução

A RFC 5789 exige aplicar o conjunto inteiro de mudanças ou nenhuma. O servidor não pode expor estado parcial; uma falha deve deixar a operação sem alterações.

A RFC 6902 mostra um test que falha e cancela todo o JSON Patch. Essa garantia começa depois que o pedido é admitido; não é poder concedido pelo anúncio. Como PATCH pode ter efeitos definidos pela aplicação em outros recursos, o limite de commit deve cobrir tudo que é diretamente afetado.

Uma implementação clara autentica, autoriza alvo e operações, valida Content-Type, interpreta a gramática, avalia If-Match e regras de domínio, prepara mudanças e confirma tudo junto. Ler Accept-Patch não inicia transação nem bloqueia versão.

Cache e assinatura mantêm seus limites

A RFC 9111 exige que caches atravessados invalidem o alvo após resposta não errônea a método inseguro. Location e Content-Location de mesma origem podem ser candidatos; outra origem não. Esse efeito segue um PATCH real, não OPTIONS com Accept-Patch, e não garante invalidação global.

A RFC 9421 permite assinar componentes escolhidos. Cobrir Accept-Patch pode proteger integridade e autenticidade sob um perfil de aplicação. Não cria a decisão de acesso. O perfil adicional teria de ligar identidade, método, alvo e conteúdo segundo sua própria política.

Implementação auditável

O cliente deve guardar separadamente URI e hora da observação, indicação do método, tipos e parâmetros, validador da versão de base e contexto de credenciais. O servidor pode anunciar capacidade em OPTIONS e, quando PATCH chegar, autenticar, autorizar, validar o formato, verificar a precondição e executar atomicamente.

Testes devem cruzar Allow sem lista, lista em GET, anúncios iguais para contas com direitos diferentes, If-Match antigo, JSON genérico recusado, efeitos distintos dos dois formatos, test falho sem mudança e anúncio assinado seguido de 403.

A página atual de errata registra três correções verificadas e uma rejeitada. A 5521 remove Content-Location do exemplo 204; a 7513 corrige apenas um link; a 3419 rejeitada não muda a norma.

Fontes