Fico um pouco triste ao ver que, depois de mais de 10 anos, não há uma resposta realmente afirmando como uma coisa solicitada no OP poderia ser projetada em uma arquitetura REST; portanto, sinto a necessidade de fazer isso agora.
Primeiras coisas primeiro, o que é REST ?! O acrônimo REST ou ReST significa "Representational State Transfer" e define a troca do estado de um recurso em um determinado formato de representação. O formato de representação é maré para o tipo de mídia negociado. No caso deapplication/html formato de representação, pode haver um fluxo de conteúdo de texto formatado em HTML processado no navegador, provavelmente após a aplicação de alguma formatação de folha de estilo para posicionar certos elementos em determinados locais.
O REST é, em princípio, uma generalização da Web navegável que todos conhecemos, embora tenha como alvo todos os tipos de aplicativos e não apenas navegadores. Portanto, por design, os mesmos conceitos que se aplicam à Web também se aplicam a uma arquitetura REST. Uma pergunta como conseguir algo de uma maneira "RESTful" resolve responder à pergunta de como conseguir algo em uma página da Web e depois aplicar os mesmos conceitos na camada de aplicativo.
Uma calculadora baseada na Web geralmente pode começar com alguma "página" que permite inserir alguns valores para calcular antes de enviar os dados inseridos para o servidor. Em HTML, isso geralmente é alcançado por meio de <form>elementos HTML que ensinam um cliente sobre os parâmetros disponíveis para definir, o local de destino para o qual enviar a solicitação e o formato de representação a ser aplicado ao enviar os dados de entrada. Isto pode ser assim:
<html>
<head>
...
</head>
<body>
<form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
<label for="firstNumber">First number:</label>
<input type="number" id="firstNumber" name="firstNumber"/>
<label for="secondNumber">Second number:</label>
<input type="number" id="secondNumber" name="secondNumber"/>
<input type="submit" value="Add numbers"/>
</form>
</body>
</html>
A amostra acima, ou seja, afirma que existem dois campos de entrada que podem ser preenchidos pelo usuário ou por outros autômatos e que, ao chamar o elemento de entrada de envio, o navegador se encarrega de formatar os dados de entrada em um application/x-www-form-urlencodedformato de representação enviado para o local de destino mencionado por meio do método de solicitação HTTP especificado, POSTneste caso. Se entrarmos 1no firstNumbercampo de entrada e 2no secondNumbercampo de entrada, o navegador gerará uma representação firstNumber=1&secondNumber=2e a enviará como a carga útil do corpo da solicitação real para o recurso de destino.
A solicitação HTTP bruta emitida para o servidor pode ser assim:
POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html
firstNumber=1&secondNumber=2
O servidor pode executar o cálculo e responder com uma página HTML adicional que contém o resultado do cálculo, conforme a solicitação indicou que o cliente entende esse formato.
Como Breton já apontou, não existe URL ou URI "RESTful". Um URI / URL é seu próprio tipo de coisa e não deve transmitir nenhum significado a um cliente / usuário. Na amostra da calculadora acima, um usuário simplesmente não está interessado para onde enviar os dados, apenas está interessado em que, ao acionar o campo de entrada de envio, a solicitação é enviada. Todas as informações necessárias para executar a tarefa já devem ser fornecidas pelo servidor.
Um navegador também pode não estar ciente de que a solicitação está realmente alimentando uma calculadora com alguns parâmetros de entrada; também pode ser algum tipo de formulário de pedido que retorna apenas a próxima representação de formulário para continuar o processo de pedido ou algum tipo totalmente diferente de recurso. Ele simplesmente executa o que a especificação HTML exige nesse caso e não se importava com o que o servidor realmente está fazendo. Esse conceito permite que um navegador use o mesmo formato de representação para fazer todo tipo de coisa, como solicitar alguns itens da sua loja on-line preferida, conversar com seus melhores amigos, acessar uma conta on-line e assim por diante.
A disponibilidade de certos elementos, como no caso do campo de entrada de envio que geralmente é renderizado como botão, define o que você deve fazer com ele. No caso de um botão ou link, basicamente, você deve clicar nele. Outros elementos podem transmitir diferentes possibilidades. Essa disponibilidade também pode ser expressa por meio de relações de link, como por exemplo, com preloadlinks anotados que basicamente informam ao cliente que ele já pode carregar o conteúdo do recurso vinculado em segundo plano, pois o usuário provavelmente irá capturar esse conteúdo a seguir. É claro que essas relações de link devem ser padronizadas ou seguir o mecanismo de extensão dos tipos de relações, conforme definido pelos links da Web. .
Esse é o conceito fundamental usado na Web e que também deve ser usado em uma arquitetura REST. De acordo com o "tio Bob", Robert C. Martin, uma arquitetura tem a ver com intenção e a intenção por trás da arquitetura REST é a dissociação de clientes de servidores para permitir que os servidores evoluam livremente no futuro sem ter medo de prejudicar os clientes. Infelizmente, isso requer muita disciplina, pois é muito fácil introduzir acoplamentos ou adicionar soluções de correção rápida para concluir o trabalho e seguir em frente. Como Jim Webber apontou em uma arquitetura REST, você, como provedor de serviços, deve tentar criar um protocolo de aplicativo de domínio semelhante a um jogo de computador baseado em texto dos anos 70 que os clientes seguirão até chegarem ao final de um processo.
O que muitas APIs chamadas "REST" infelizmente fazem na realidade é tudo, menos isso. Você vê a troca principalmente de dados baseados em JSON, especificados em uma documentação externa específica da API que geralmente é difícil de integrar dinamicamente em tempo real. O formato em que uma solicitação precisa se parecer também é codificado na documentação externa, o que leva a muitas URIs de interpretação de implementação para retornar tipos predefinidosem vez de usar algum formato de representação comum negociado antecipadamente. Isso impede que os servidores sejam alterados, pois agora os clientes esperam receber um determinado formato de dados (observe o formato de não representação!) Para URIs predefinidos. Essa troca personalizada de formato de dados impede ainda que os clientes interajam com outras APIs, pois o "formato de dados" geralmente é uma maré para uma API específica. Conhecemos esse conceito no passado a partir de tecnologias RPC, como Corba, RMI ou SOAP, que condenamos como de alguma forma más, embora Peppol tenha se mudado para ele novamente substituindo o AS2 pelo AS4 como protocolo de transferência padrão recentemente.
Com relação à pergunta real, o envio de dados como arquivo csv não é diferente de usar application/x-www-form-urlencodedrepresentação ou algo semelhante. Jim Webber deixou claro que, afinal, o HTTP é apenas um protocolo de transporte cujo domínio de aplicativo é a transferência de documentos pela Web . Cliente e servidor devem ter pelo menos suporte, text/csvconforme definido na RFC 7111 . Esse arquivo CSV pode ser gerado como consequência do processamento de um tipo de mídia que define elementos de formulário, um elemento ou atributo de destino para enviar a solicitação e o método HTTP para executar o upload da configuração.
Existem alguns tipos de mídia compatíveis com formulários como HTML , HAL Forms , halform , ion ou Hydra . Atualmente, porém, não conheço um tipo de mídia que possa codificar automaticamente os dados de entrada text/csvdiretamente, portanto, pode ser necessário definir e registrar o registro de tipo de mídia da IANA. .
O upload e o download do conjunto completo de parâmetros não devem ser um problema, eu acho. Como mencionado anteriormente, o URI de destino não é relevante, pois um cliente apenas usará o URI para recuperar novo conteúdo para processar. A filtragem por data comercial também não deve ser difícil. Aqui o servidor deve, no entanto, o cliente com todas as possibilidades que o cliente simplesmente pode escolher. Nos últimos anos, o GraphQL e o RestQL evoluíram, introduzindo uma linguagem semelhante ao SQL que pode ser direcionada a um determinado endpoint para obter uma resposta filtrada. No entanto, no verdadeiro sentido REST, isso viola a idéia por trás do REST como: a) GraphQL, ou seja, usa apenas um único terminal que de alguma forma impede o uso ideal do armazenamento em cache eb) requer o conhecimento dos campos disponíveis com antecedência, o que pode levar à introdução de um acoplamento de clientes. para o modelo de dados base do recurso.
A ativação ou desativação de determinados parâmetros de configuração é simplesmente uma questão de acionar os controles hipermídia que fornecem essa disponibilidade. Nos formulários HTML, pode ser uma caixa de seleção simples ou uma seleção de várias linhas em uma lista ou esse tipo. Dependendo do formulário e do método que ele define, ele poderá enviar a configuração inteira via PUTou ser inteligente sobre as alterações feitas e realizar apenas uma atualização parcial via PATCH. O último requer basicamente um cálculo da representação de mudança para aquele atualizado e alimenta o servidor com as etapas necessárias para transformar a representação atual na desejada. De acordo com a especificação PATH, isso deve ser feito em uma transação para que todas ou nenhuma das etapas sejam aplicadas.
O HTTP permite e incentiva um servidor a validar uma solicitação recebida antecipadamente antes de aplicar as alterações. Para PUT, os estados de especificação:
Um servidor de origem DEVE verificar que a representação PUT é consistente com quaisquer restrições que o servidor tenha para o recurso de destino que não pode ou não será alterado pelo PUT. Isso é particularmente importante quando o servidor de origem usa informações de configuração interna relacionadas ao URI para definir os valores dos metadados de representação nas respostas GET. Quando uma representação PUT é inconsistente com o recurso de destino, o servidor de origem DEVE torná-los consistentes, transformando a representação ou alterando a configuração de recursos, ou responde com uma mensagem de erro apropriada contendo informações suficientes para explicar por que a representação é inadequada. Os códigos de status 409 (Conflito) ou 415 (Tipo de mídia não suportado) são sugeridos,
Por exemplo, se o recurso de destino estiver configurado para sempre ter um Tipo de Conteúdo de "text / html" e a representação sendo PUT possuir um Tipo de Conteúdo de "image / jpeg", o servidor de origem deverá executar um dos seguintes procedimentos:
uma. reconfigure o recurso de destino para refletir o novo tipo de mídia;
b. transforme a representação PUT em um formato consistente com o do recurso antes de salvá-lo como o novo estado do recurso; ou,
c. rejeite a solicitação com uma resposta 415 (Tipo de mídia não suportada) indicando que o recurso de destino está limitado a "text / html", talvez incluindo um link para um recurso diferente que seria um destino adequado para a nova representação.
O HTTP não define exatamente como um método PUT afeta o estado de um servidor de origem além do que pode ser expresso pela intenção da solicitação do agente do usuário e pela semântica da resposta do servidor de origem. ...
Para resumir esta postagem, você deve usar um tipo de mídia existente que permita ensinar um cliente sobre os parâmetros de entrada necessários ou suportados, o local de destino para o qual enviar a solicitação, a operação a ser usada e o tipo de mídia a solicitação deve ser formatada ou definir sua própria que você registra na IANA. O último pode ser necessário se você deseja converter a entrada emtext/csve faça o upload da representação CSV para o servidor. A validação deve ocorrer antes que as alterações sejam aplicadas ao recurso. O URI real não deve ser relevante para clientes, a não ser para determinar para onde enviar a solicitação e, como tal, pode ser escolhido livremente por você, o implementador do serviço. Ao seguir estas etapas, você obtém a liberdade de alterar o lado do servidor a qualquer momento e os clientes não quebram como consequência se oferecerem suporte aos tipos de mídia usados.