Como uma API REST deve manipular solicitações PUT para recursos parcialmente modificáveis?

Suponha que uma API REST, em resposta a uma GETsolicitação HTTP , retorne alguns dados adicionais em um subobjeto owner:

{
  id: 'xyz',
  ... some other data ...
  owner: {
    name: 'Jo Bloggs',
    role: 'Programmer'
  }
}

Claramente, não queremos que ninguém possa PUTvoltar atrás.

{
  id: 'xyz',
  ... some other data ...
  owner: {
    name: 'Jo Bloggs',
    role: 'CEO'
  }
}

e ter esse sucesso. De fato, provavelmente nem vamos implementar uma maneira de que isso possa ser bem-sucedido, nesse caso.

Mas essa pergunta não é apenas sobre subobjetos: o que, em geral, deve ser feito com dados que não devem ser modificáveis ​​em uma solicitação PUT?

Deveria estar ausente a solicitação PUT?

Deve ser descartado silenciosamente?

Ele deve ser verificado e se diferir do valor antigo desse atributo, retorne um código de erro HTTP na resposta?

Ou devemos usar patches JSON RFC 6902 em vez de enviar o JSON inteiro?

Não existe uma regra, na especificação do W3C ou nas regras não oficiais do REST, que diz que um PUTdeve usar o mesmo esquema / modelo que o correspondente GET.

É bom se eles são semelhantes , mas não é incomum PUTfazer as coisas de maneira um pouco diferente. Por exemplo, vi muitas APIs que incluem algum tipo de ID no conteúdo retornado por a GET, por conveniência. Mas com a PUT, esse ID é determinado exclusivamente pelo URI e não tem significado no conteúdo. Qualquer ID encontrado no corpo será ignorado silenciosamente.

O REST e a web em geral estão fortemente ligados ao Princípio da Robustez : "Seja conservador no que faz [envie], seja liberal no que aceita". Se você concorda filosoficamente com isso, a solução é óbvia: ignore todos os dados inválidos nas PUTsolicitações. Isso se aplica aos dados imutáveis, como no seu exemplo, e às bobagens reais, por exemplo, campos desconhecidos.

PATCHé potencialmente outra opção, mas você não deve implementá- PATCHlo, a menos que realmente ofereça suporte a atualizações parciais. PATCHsignifica apenas atualizar os atributos específicos que incluo no conteúdo ; isso não significa substituir a entidade inteira, mas excluir alguns campos específicos . Na verdade, o que você está falando não é uma atualização parcial, é uma atualização completa, idempotente e tudo mais, é apenas que parte do recurso é somente leitura.

Uma coisa boa a fazer se você escolher essa opção seria enviar de volta um 200 (OK) com a entidade atualizada real na resposta, para que os clientes possam ver claramente que os campos somente leitura não foram atualizados.

Certamente, algumas pessoas pensam o contrário - que deve ser um erro tentar atualizar uma parte somente leitura de um recurso. Há alguma justificativa para isso, principalmente com base em que você definitivamente retornaria um erro se todo o recurso fosse somente leitura e o usuário tentasse atualizá-lo. Definitivamente, isso contraria o princípio da robustez, mas você pode considerar que é mais "auto-documentável" para os usuários da sua API.

Existem duas convenções para isso, as quais correspondem às suas idéias originais, mas eu as expandirei. O primeiro é proibir que os campos somente leitura apareçam no conteúdo e retornar um HTTP 400 (Solicitação incorreta), se houver. APIs desse tipo também devem retornar um HTTP 400 se houver outros campos não reconhecidos / inutilizáveis. O segundo é exigir que os campos somente leitura sejam idênticos ao conteúdo atual e retornar um 409 (Conflito) se os valores não corresponderem.

Eu realmente não gosto da verificação de igualdade com 409 porque, invariavelmente, exige que o cliente faça um GETpara recuperar os dados atuais antes de poder fazer um PUT. Isso não é legal e provavelmente levará a um desempenho ruim, para alguém, em algum lugar. Eu também realmente não gosto do 403 (Proibido) por isso, pois implica que todo o recurso está protegido, não apenas uma parte dele. Portanto, minha opinião é que, se você absolutamente precisar validar, em vez de seguir o princípio de robustez, valide todas as suas solicitações e retorne 400 para qualquer um que tenha campos extras ou não graváveis.

Verifique se o seu 400/409 / Whatever inclui informações sobre qual é o problema específico e como corrigi-lo.

Ambas as abordagens são válidas, mas eu prefiro a primeira, de acordo com o princípio da robustez. Se você já experimentou trabalhar com uma grande API REST, apreciará o valor da compatibilidade com versões anteriores. Se você decidir remover um campo existente ou torná-lo somente leitura, será uma alteração compatível com versões anteriores se o servidor simplesmente ignorar esses campos e os clientes antigos ainda funcionarem. No entanto, se você fizer uma validação estrita do conteúdo, ele não será mais compatível com versões anteriores e os clientes antigos deixarão de funcionar. O primeiro geralmente significa menos trabalho para o mantenedor de uma API e seus clientes.

Potência Idem

Após o RFC, um PUT teria que entregar um objeto completo ao recurso. A principal razão disso é que o PUT deve ser idempotente. Isso significa que uma solicitação repetida deve ser avaliada para o mesmo resultado no servidor.

Se você permitir atualizações parciais, ela não poderá mais ser idem-potente. Se você tem dois clientes. Cliente A e B, o seguinte cenário pode evoluir:

O cliente A obtém uma imagem das imagens de recursos. Isso contém uma descrição da imagem, que ainda é válida. O cliente B coloca uma nova imagem e atualiza a descrição de acordo. A imagem mudou. O cliente A vê, ele não precisa alterar a descrição, porque é como ele deseja e colocar apenas a imagem.

Isso levará a uma inconsistência, a imagem tem os metadados incorretos anexados!

Ainda mais irritante é que qualquer intermediário pode repetir a solicitação. Caso decida de alguma forma, o PUT falhou.

O significado de PUT não pode ser alterado (embora você possa usá-lo mal).

Outras opções

Felizmente, há uma outra opção, este é o PATCH. PATCH é um método que permite atualizar parcialmente uma estrutura. Você pode simplesmente enviar uma estrutura parcial. Para aplicativos simples, isso é bom. Não é garantido que este método seja idem potente. O cliente deve enviar uma solicitação no seguinte formato:

PATCH /file.txt HTTP/1.1
Host: www.example.com
Content-Type: application/example
If-Match: "e0023aa4e"
Content-Length: 20
{fielda: 1, fieldc: 2}

E o servidor pode responder novamente com 204 (Sem conteúdo) para sinalizar o sucesso. Por erro, você não pode atualizar uma parte da estrutura. O método PATCH é atômico.

A desvantagem desse método é que nem todos os navegadores suportam isso, mas essa é a opção mais natural em um serviço REST.

Exemplo de solicitação de patch: http://tools.ietf.org/html/rfc5789#section-2.1

Correção de Json

A opção json parece ser bastante abrangente e uma opção interessante. Mas pode ser difícil de implementar para terceiros. Você precisa decidir se sua base de usuários pode lidar com isso.

Também é um pouco complicado, porque você precisa criar um pequeno intérprete que converta os comandos em uma estrutura parcial, que você usará para atualizar seu modelo. Esse intérprete também deve verificar se os comandos fornecidos fazem sentido. Alguns comandos se cancelam. (escreva fielda, exclua fielda). Acho que você deseja denunciar isso ao cliente para limitar o tempo de depuração do lado dele.

Mas se você tiver tempo, essa é uma solução realmente elegante. Você ainda deve validar os campos, é claro. Você pode combinar isso com o método PATCH para permanecer no modelo REST. Mas acho que o POST seria aceitável aqui.

Indo mal

Se você decidir optar pela opção PUT, o que é um pouco arriscado. Então você deve pelo menos não descartar o erro. O usuário tem uma certa expectativa (os dados serão atualizados) e, se você quebrar isso, não dará um bom tempo a alguns desenvolvedores.

Você pode optar por sinalizar de volta: 409 Conflito ou 403 Proibido. Depende de como você olha o processo de atualização. Se você o vir como um conjunto de regras (centralizado no sistema), o conflito será mais agradável. Algo como, esses campos não são atualizáveis. (Em conflito com as regras). Se você o vir como um problema de autorização (centrado no usuário), deverá retornar proibido. Com: você não está autorizado a alterar esses campos.

Você ainda deve forçar os usuários a enviar todos os campos modificáveis.

Uma opção razoável para impor isso é configurá-lo como um sub-recurso, que oferece apenas os dados modificáveis.

Opinião pessoal

Pessoalmente, eu iria (se você não precisar trabalhar com navegadores) pelo modelo PATCH simples e depois o estenderia com um processador de patch JSON. Isso pode ser feito diferenciando-se nos tipos mimetizados: O tipo mime do patch json:

application / json-patch

E json: application / json-patch

facilita a implementação em duas fases.