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

(Obrigatório)

Objetivo

        Definir um padrão para que nossos serviços atendam aos requisitos de serviços SOA

(Obrigatório)

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 deficiências dos mesmos e tratá-las. 

<Regra de negócio é o que define a forma de fazer o negócio, o processo definido e/ou as regras que devem ser contempladas. Devem ser descritas restrições, validações, condições e exceções do processo. Caso necessário, incluir neste capítulo também regras de integridade que devem ser observadas no momento do desenvolvimento>.

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

• Criar o campo “% Mínimo Espécie” (AAA_PERESP) onde o usuário informará o % que o aluno pagará em dinheiro. Esse % poderá ser alterado durante a negociação.
• Criar o campo “Referência Mínima para Cálculo” (AAA_REFCAL) onde o usuário informará um dos 4 valores disponíveis para pagamento das mensalidades  como a referência mínima para calcular o débito total do aluno.
• Criar o parâmetro MV_ACPARNE que definirá se as informações de “% Mínimo Espécie” e “Referência Mínima para Cálculo” serão obrigatórias.
• O parâmetro MV_ACPARNE deve ter as seguintes opções: 1=Obrigatório e 2=Opcional. Deve ser inicializado como opcional>.

Tabelas Utilizadas

• SE2 – Cadastro de Contas a Pagar
• FI9 – Controle de Emissão de DARF>.

Opcional

Protótipo de Tela

<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.

Protótipo 01

 Image Removed

Opcional

Fluxo do Processo

<Nesta etapa incluir representações gráficas que descrevam o problema a ser resolvido e o sistema a ser desenvolvido. Exemplo: Diagrama - Caso de Uso, Diagrama de Atividades, Diagrama de Classes, Diagrama de Entidade e Relacionamento e Diagrama de Sequência>. 

Opcional

Dicionário de Dados

Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/

(Opcional)

Grupo de Perguntas

<Informações utilizadas na linha Protheus>.

Nome: FINSRF2

(Opcional)

Consulta Padrão

<Informações utilizadas na linha Protheus>

Consulta: AMB

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 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). 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 e Javascript), nossa arquitetura sofreu uma evolução para expor nossos serviços. Hoje temos uma camada que expõe os serviços em HTTP (REST/JSON ou XML) utilizando WebAPI 2.0, com isso qualquer aplicação, inclusive o FrameHTML, 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.

          No primeiro momento para tornar o desenvolvimento produtivo, criamos um serviço RMSDataServerController que recebe o nome do DataServer como o parâmetro. Para entregar ao DataServer em questão o contexto da aplicação o FrameHTML tem um interceptor que resgata o contexto (está armazenado em uma variável chamada currentContext no escopo do AngularJS) e adiciona todas as propriedades do contexto no header da requisição. O RMSDataServerController resgata o contexto do header e entrega ao DataServer em questão.

          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 relacionamos às mudanças que teremos.

          Ao confrontarmos os conceitos SOA e 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 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 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

      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.

(Opcional)

Estrutura de Menu

<Informações utilizadas na linha Datasul>.

Procedimentos

Programas

Cadastro de Papéis

<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.

<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.