Histórico da Página
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|
(Obrigatório)
Informações Gerais
Especificação | |||
Produto | Framework | Módulo | Globais |
Segmento Executor |
| ||
Projeto1 |
| IRM1 |
|
Requisito1 | Subtarefa1 | FRW_FRW002-80 | |
Chamado2 |
| ||
País | ( X ) Brasil ( ) Argentina ( ) Mexico ( ) Chile ( ) Paraguai ( ) Equador ( ) USA ( ) Colombia ( ) Outro _____________. | ||
Outros | <Caso necessário informe outras referências que sejam pertinentes a esta especificação. Exemplo: links de outros documentos ou subtarefas relacionadas>. |
Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos).
Objetivo
Em Em consonância com o mercado e com a estratégia da TOTVS, estamos expondo nossos serviços para consumo externo em um padrão restREST, inclusive os DataServers.
O O FrameHTML por ser tratar de uma aplicação baseada em javascript e HTML irá usufruir dessa infra estrutura infraestrutura criada.
Diante disso surge surgem algumas definições e mudanças necessárias para que sejamos 100% SOA e, consequentemente, tenhamos nossos serviços prontos para serem consumidos por qualquer aplicativo.
Definição da Regra de Negócio
Nossa arquitetura está preparada para ser 100% SOA, porém precisamos pensar como os nossos DataServers funcionam para então perceber as as deficiências do mesmo dos mesmos e tratá-las.
Cenário atual:
Temos duas formas de chamadas de serviços no RM.Host, são elas:
- Chamada Client (Winforms/WebForms)
Neste caso, a Lib se se encarrega de recuperar o RMSContext que está no contexto da aplicação cliente (WinForms/WebForms) , e entregar para o serviço no server (RM.Host), desta . Esta forma permitiu que os DataServers de produto fossem herdados do RMSDataServer , e as informações de contexto ficassem disponíveis nos serviços (ReadView, ReadRecord,etc) executados. - Chamada WebService (SOAP/REST)
Para expor nossos DataServers, foi criado um WebService genérico que recebe como parâmetro o nome do DataServer, o contexto (coligada, sistema, usuário, etc.) e demais parâmetros pertinentes ao serviço executado (ReadView, ReadRecord, etc.), com isso o DataServer do produto recebe o contexto que ele precisa para ser executado.
Com a chegada do FrameHTML (100% html HTML e javascriptJavascript), nossa arquitetura sofreu uma evolução para expor nossos serviços, hoje . Hoje temos uma camada que expõe nossos os serviços em HTTP (rest REST/ json JSON ou xmlXML) utilizando WebAPI 2.0, com isso qualquer aplicação, inclusive o FrameHTML podem , pode chamar nossos serviços, porém como vimos, nossos DataServers dependem de um contexto de excuçãoexecução (RMSContext). Contudo, porém o RMSContext traz consigo muitas informações que podem ou não ser uteis úteis à execução do DataServer em questão.
No primeiro momento para tornar o desenvolvimento produtivo, criamos um serviço RMSDataServerController que recebe o nome do dataServer DataServer como o parâmetro, para . Para entregar ao DataServer em questão o contexto da aplicação o FrameHTML têm tem um interceptor que resgata o contexto (está armazenado em uma variável chamada currentContext no escopo do angularAngularJS) e adiciona todas as propriedades do contexto no header da requisição, e o . O RMSDataServerController resgata o contexto no do header e entrega ao DataServer em questão.
Como podemos notar o nosso serviço depende de informações de contexto e que são trafegadas no header da requisição, neste . Neste ponto precisamos entender alguns termos utilizados na arquitetura SOA que estão diretamente relacionamos às mudanças que teremos.
Termo | Definição / Comentário |
---|---|
Serviço | É uma função independente, sem estado (stateless) que aceita uma ou mais requisições e devolve uma ou mais respostas através de uma interface padronizada e bem definida. Serviços podem também realizar partes discretas de um processo tal como editar ou processar uma transação. Serviços não devem depender do estado de outras funções ou processos. A tecnologia utilizada para prover o serviço, tal como uma linguagem de programação, não pode fazer parte da definição do serviço. |
Orquestração | Processo de sequenciar serviços e prover uma lógica adicional para processar dados. Não inclui uma representação de dados. |
Stateless | Não depende de nenhuma condição pré-existente. Os serviços não devem depender de condições de outros serviços. Eles recebem todas as informações necessárias para prover uma resposta consistente. O objetivo de buscar a característica de stateless dos serviços é possibilitar que o consumidor do serviço possa sequenciá-lo, ou seja, orquestrá-los em vários fluxos (algumas vezes chamados de pipelines) para executar a lógica de uma aplicação. |
Provedor | O recurso que executa o serviço em resposta a uma requisição de um consumidor. |
Consumidor | É quem consome ou pede o resultado de um serviço fornecido por um provedor. |
Descoberta | SOA se baseia na capacidade de identificar serviços e suas características. ConseqüentementeConsequentemente, esta arquitetura depende de um diretório que descreva quais os serviços disponíveis dentro de um domínio. |
Binding | A relação entre os serviços do provedor e do consumidor deve ser idealmente dinâmica; ela é estabelecida em tempo de execução através de um mecanismo de binding. |
Ao confrontarmos os conceitos SOA e as definições da TOTVS com o que está implementado hoje, vemos que precisamos das seguintes mudanças:
- O serviço deve ser stateless, hoje nossos DataServers dependem do contexto.
- O serviço deve ser auto-documentável, portanto esperar somente o que precisa para execução, o RMSContext têm muita informação que pode ser dispensável para determinadas rotinas.
- Nenhuma informação deve ser enviada pelo header, pois dificulta a documentação e utilização.
O Controller genérico RMSDataServerController criado na WebAPI juntamente com o intercepctor criado no FrameHTML permanecerá funcionando para manter compatibilidade. Porém é expressamente recomentado recomendado que as novas funcionalidades migradas para o FrameHTML nasçam respeitando todas as premissas apontadas acima.
Veja o desenho simplificado da nossa nova estrutura.
Outro ponto importante que devemos tratar é a segurança das informações armazenadas no clientcliente.
Vamos nos ater a falar na aplicação web (Portal), hoje . Hoje grande parte das informações armazenadas no lado cliente, como por exemplo o contexto da aplicação (RMSContext), está na session sessão do Asp.Net e consequentemente protegidas. Já no FrameHTML por se tratar de uma aplicação feita em HTML e javascript não possui o conceito de session, portanto deve-se observar quais informações estão sendo armazenadas no lado cliente, e criar mecanismos de proteção do lado server, para impedir que essas informações sejam alteradasASP.NET(Sevidor Web na imagem acima) e, consequentemente, protegida.
Já o FrameHTML, entrega somente os componentes em HTML e Javascript, ou seja, não possui uma implementação em cima de servidor web(isso deverá ser feito pelo produto), portanto se for utilizar a infraestrutura do mesmo(angularJS) para armazenar informações, lembre-se que a mesma é passível de alteração por estar no Browser. Veja o exemplo abaixo:
O usuário (XXXU) loga e se autentica e acessa a funcionalidade de histórico salarial, considere . Considere que o DataServer de histórico salarial utilize o usuário do contexto para filtrar o retorno dos dados, ou a segurança da informação. Neste ponto temos a seguinte diferença entre o Portal e o FrameHTML:
Portal:
O RMSContext está na session sessão do asp.net que por sua vez protegida, portanto ASP.NET, protegida pelo servidor de aplicação. Portanto, podemos confiar na informação setada no atribuída ao RMSContext.
FrameHTML:
O RMSContext está no escopo do angular na aplicação, AngularJS, ou seja, no navegador e totalmente vulnerável à intervenção do usuário, portanto neste caso ele poderia alterar o usuário do RMSContext que acessar o histórico salarial de um usuário diferente do usuário logado.
. Portanto, passível de alteração pelo usuário que se autenticar para acesso ao histórico salarial. Outro exemplo seria uma chamada de WebService, logando autenticando-se com um usuário e passando o outro usuário do no Contexto qualquer usuário que desejar.
Diante do exposto é expressamente recomendado que os serviços utilizem o usuário do
principalPrincipal (carteirinha), pois esse a Lib garante
, já. Já o usuário do RMSContext não é garantido pela Lib e o exemplo acima é apenas um de várias formas que temos de enviar um usuário logado diferente do usuário do contexto.
Pra finalizar vamos ver algumas dicas para criação dos EndPoints:
- Requisitos fundamentais para API
Lembre-se que você está desenvolvendo uma interface que será utilizada por outro desenvolvedor, então, é importante tomar alguns cuidados:
- possuir documentação adequada;
- ser o mais simples e intuitivo possível (affordance), seja na URI, payload, request ou response;
- deve-se levar em conta a experiência do usuário. Procurar seguir o padrão já utilizado pelo mercado, evitar “coisas” mirabolantes;
- manter a padronização, nas URIs, tipo de retorno, etc.
- Padrões HTTP
REST é baseado no protocolo HTTP, é importante seguir os padrões definidos por ele e aplicá-los onde eles fazem sentido, por exemplo, nos status code de retorno de um método. - Utilize JSON
Evite utilizar XML, eles são verbosos, difíceis de ler. Basta analisar o gráfico abaixo extraído do Google Trends. Nele fica claro o crescente interesse na utilização de APIs JSON frente a APIs XML. - URI, recursos
Um dos princípios fundamentais de REST é separar a API em recursos semânticos, que serão manipulados através de solicitações HTTP, e eles devem fazer sentido para os usuários da API.
A identificação do recurso deve ser um substantivo e não um verbo. Não há uma regra que diga se o recurso deve estar no singular ou plural, porém, o escolhido, deve seguir um padrão em toda a API. Exemplo de recursos em uma API disponibilizada em um domínio denominado “meudominioxpto.com”:/cliente
/produto
/pedidoE como lidar com relações? Por exemplo, o telefone de um cliente.
/cliente/33/ telefone – manipular os telefones do cliente 33;
/cliente/33/ telefone/10 – manipular os telefones 10 do cliente 33. - Verbos HTTP
Use o verbo correto para as operações de CRUD (Create, Read, Update e Delete):
- Status code HTTP
O uso correto do status code facilita muito a vida dos clientes (consumidores) de sua API, utilize-os da maneira correta e padronizada.
- Passagem de Parâmetros
Para API REST, as mais mais utilizadas são: Path Parameters; Query Parameters; Header Parameters e Body Parameters. É uma boa prática utilizá-las da seguinte maneira: - Por fim.
Quando for construir um serviço, pense que o seu serviço deve ser:- Stateless
- Simples de usar
- Auto documentável
- Esperar somente o que precisa
- Deve confiar somente no usuário da carteirinha(Principal), todas as outras informações(RMSContext por exemplo) são vulneráveis.
- Assinatura padronizada.
Este documento é material de especificação dos requisitos de inovação, trata-se de conteúdo extremamente técnico. |
---|