Representar ações (verbos) no REST URI

Tenho uma operação de impressão para executar nos documentos dos meus clientes. Também preciso que outras operações padrão sejam executadas, como adicionar, atualizar e excluir. então, eu tenho o seguinte:

• Para criar um novo cliente:
  URI = / customer / {id}, digite = POST, Methodname = CreateCustomer ()
• Para atualização:
  URI: / customer / {id}, digite = PUT, método = UpdateCstomer ()
• Para Excluir cliente:
  URI = / customer / {id}, digite = DELETE, Nome do método = DeleteCustomer ()
• Para Ver:
  URI: / cliente / {id}, escreva = GET, method = GetCustomer ()

Agora, se eu precisar imprimir um documento para esse cliente, preciso de uma função de impressão. Meu URI pode ficar assim: / customer / {id}, tipo = POST, método = PrintCustomer (). Mas eu usei esse tipo de URI e POST para CreateCustomer. Eu queria que o URI tivesse a seguinte aparência: / customer / Print / {id}, digite = POST, método = PrintCustomer ().

Mas não posso ter o verbo "Imprimir" no meu URI. Qual é a melhor forma de fazer isso? Pensei em / customer / document / {id} como o URI ... mas vou encontrar o mesmo problema. Eu teria as operações CRUD no "documento". Então, novamente, acabo com o que eu usaria para "imprimir". Por favor informar.

POSTnão significa "criar", significa "processo". Você pode criar um novo recurso postando uma solicitação adequada em um recurso existente (por exemplo, postar /customerspara criar um novo cliente). Mas você também pode usar POSTpara preencher todas as outras ações que não correspondem a um paradigma CRUD puro.

No caso de impressão, você deve considerar o ato de imprimir como um recurso em si. Você está pedindo ao sistema para criar um "trabalho de impressão" para você. Isso significa que você pode ter um prints/recurso que atua como o contêiner para todas as impressões solicitadas. Quando você deseja imprimir algo em POSTum documento para este recurso, que contém todas as informações sobre a impressão que deseja criar, identificando os recursos que deseja imprimir com links para eles.

Como um documento JSON, poderia ser assim:

{
   contents: ["http://site/customers/12345"],
   paper-size: "A4",
   duplex: "true"
}

Obviamente, você precisa personalizá-lo para ser relevante para o que deseja fazer. O principal é que você esteja identificando outros recursos para imprimir especificando o URL deles.

Em resposta à solicitação, você pode simplesmente devolver um 200 OKou um 204 No-Contente tratá-lo como um processo de ignorar. No entanto, se você quiser aprimorá-lo, poderá retornar 201 Createde especificar o URL do trabalho de impressão recém-criado, por exemplo /prints/12345.

Um usuário pode executar um GETno recurso para ver o status do trabalho de impressão (pendente, em andamento etc.) ou pode solicitar que o trabalho seja cancelado com a emissão de a DELETE.

Depois de reformular o problema em termos de recurso, o design do RESTful deve vir naturalmente e dar a você a oportunidade de expandir e aprimorar de maneiras que talvez você não tenha considerado imediatamente.

Eu fiz isso antes. Para imprimir um documento, acabei de retornar uma versão em PDF de um recurso. O cliente só precisa enviar uma solicitação GET para o recurso com o cabeçalho Accept application / pdf.

Isso também evita a criação de um novo URI para recursos temporários, como trabalho de impressão. O uso do cabeçalho HTTP também faz parte do REST e mantém o URI limpo.

Basta adicionar um parâmetro ao GET do URI atual

É bastante típico usar um URI para várias ações.

Se você estiver falando do mesmo recurso, mas de uma ação diferente, você o definiria como um parâmetro.

/ customer / {id}? print = true

Então, onde você define seu método GET, detecta a presença do parâmetro de impressão e o trata de maneira diferente.

REST é definido da seguinte maneira:

• POST - Crie um registro, ativo ou recurso
• PUT - Atualização, um registro, ativo ou recurso
• DELETE - Remover um, registro, ativo ou recurso

GET, por outro lado, deve ser usado de várias maneiras, porque normalmente existem muitas formas diferentes de recuperar um recurso. É também por isso que as solicitações GET são representadas como uma sequência de consultas. Se você estivesse trabalhando com um recurso de banco de dados, estaria literalmente recuperando uma visualização por meio de uma consulta, mas o REST é intencionalmente abstraído para um nível superior porque foi projetado para lidar com muitos tipos diferentes de recursos.

A especificação REST é bastante prospectiva, embora as APIs estejam apenas começando a usá-la recentemente.

Se você estiver interessado em aprender mais sobre os protocolos REST, sugiro que você leia " Aborrecedores que odeiam o ódio ".

Atualizar:

@ Shauna apontou um buraco interessante no meu raciocínio. Não há verdadeiro caminho certo e muitos formulários são considerados aceitáveis. Pensei um pouco mais e, como o uso pretendido é transformar os dados em uma representação diferente, faz sentido definir a transformação como um novo tipo MIME.

Por exemplo, você pode representar o URI como:

/customer/{id}+print

Onde você pode definir a resposta Content-Type como text / html + print. Dessa forma, você também teria a opção de definir mais transformações no futuro.

Por exemplo:

// for application/json
/customer/{id}+json

// for application/atom+xml
/customer/{id}+atom

De qualquer maneira, todas as formas são aceitáveis. A implementação que você decide depende mais da preferência pessoal e dos recursos do seu servidor.

Aparte: Deixe-me esclarecer, pois parece haver alguma confusão. O parâmetro de consulta 'print' e / ou tipo de conteúdo é usado para especificar como o recurso é transformado. Não é como acionar um trabalho de impressão físico. Por motivos de segurança, o acesso no nível do hardware é sempre deixado para o usuário / cliente / navegador.