Histórico da Página

(Obrigatório)

Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

        Definir um padrão para que nossos serviços atendam às premissas de serviços SOA e as premissas definidas pela TOTVS.

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 REST, inclusive os DataServers.

        O FrameHTML por ser tratar de uma aplicação baseada em javascript e HTML irá usufruir dessa infraestrutura criada.

        Diante disso 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:

1. 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.
   
   
   
2. 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 execução (RMSContext). Contudo, o RMSContext traz consigo muitas informações que podem ou não ser úteis à execução do DataServer em questão.

          Para No primeiro momento para tornar o desenvolvimento produtivo no primeiro momento, criamos um serviço RMSDataServerController que recebe o nome do dataServer DataServer como o parâmetro, e 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, por sua vez o . O RMSDataServerController resgata o contexto no do header e entrega ao DataServer em questão.

            O exposto acima reforça a necessidade da nossa solução ser 100% SOA(Arquitetura Orientada a Serviços), antes de continuarmos, vamos entender alguns termos utilizamos Como podemos notar o nosso serviço depende de informações de contexto que são trafegadas no header da requisição. Neste ponto precisamos entender alguns termos utilizados na arquitetura SOA que estão diretamente relacionados relacionamos às nossas mudanças que teremos.

              Ao confrontarmos os conceitos SOA e Definições as definições da TOTVS com o que está implementado hoje, vemos que precisamos das seguintes mudanças:

1. O serviço deve ser stateless, hoje dependemos nossos DataServers dependem do contexto.
2. O serviço deve ser auto-documentável, portanto esperar somente o que precisa para execução, o RMSContext têm muito muita informação que é pode ser dispensável para determinadas rotinas.
3. 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 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.

                                                                                                                  Image Added

         Nossa solução começou a construir um novo portal, porém como o FrameHTML é baseado em HTML e javascript não temos um conceito de 

Novo cenário:

<Na tabela abaixo informe quais são as rotinas envolvidas, o tipo de operação, a opção de menu e se necessário uma breve descrição das regras de negócio relacionadas a rotina>.

Exemplo de Aplicação: 

Outro ponto importante que devemos tratar é a segurança das informações armazenadas no cliente.

      Vamos nos ater a falar na aplicação web (Portal). Hoje grande parte das informações armazenadas no lado cliente, como por exemplo o contexto da aplicação (RMSContext), está na sessão do ASP.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 (U) se autentica e acessa a funcionalidade de histórico salarial. 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 sessão do ASP.NET, protegida pelo servidor de aplicação. Portanto, podemos confiar na informação atribuída ao RMSContext.

       FrameHTML:

                O RMSContext está no escopo do AngularJS, ou seja, no navegador e totalmente vulnerável à intervenção do usuário. 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, autenticando-se com um usuário e passando outro usuário no Contexto.

       Diante do exposto é expressamente recomendado que os serviços utilizem o usuário do Principal (carteirinha), pois esse a Lib garante. 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:

1.  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.
   
   
   
2.  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.
   
   
   
3. 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.
   
   Image Added
   
   
   
   
4. 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
                    /pedido

   E 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.

   
   
   
5. Verbos HTTP
   Use o verbo correto para as operações de CRUD (Create, Read, Update e Delete):
   
                Image Added
   
   
6. 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.
   
               Image Added
               
   
   
   
7. 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:
   
   
   Image Added
   
   
8. Por fim.
   Quando for construir um serviço, pense que o seu serviço deve ser:
   1. Stateless
   2. Simples de usar
   3. Auto documentável
   4. Esperar somente o que precisa
   5. Deve confiar somente no usuário da carteirinha(Principal), todas as outras informações(RMSContext por exemplo) são vulneráveis.
   6. Assinatura padronizada.