Trabalhando na evolução tecnológica dos sistemas da Totvs, o REST Server do Protheus vem passando por algumas modernizações e isso vem sendo realizado através da parceria entre os times da Tecnologia e do Framework.

O time da Tec vem disponibilizando novos recursos nas camadas do binário e da tlppCore, enquanto o time do Frame vem incorporando e compatibilizando esses novos recursos aos que já tínhamos na versão atual do REST.

Para entender bem essas novidades, precisamos entender quais são os componentes disponíveis, a responsabilidade de cada componente e qual time é responsável por cada um deles.

01. REST ADVPL

A partir de agora, vamos chamar nossa versão atual de REST ADVPL.

O REST ADVPL, que é mantido pelo time de Framework, foi construído quase em sua totalidade em ADVPL, utilizando do binário apenas alguns componentes de socket para comunicação e alguns componentes de controle de execução de jobs.

Foram criadas camadas de parse de mensagem HTTP e de controle da arquitetura REST, organizados em accept de requisição e de processamento, com controle de ambiente pré carregado e de autenticação para então passar para a camada de negócio realizar seu processamento e resposta.

Para criar uma API, é necessário implementar uma nova classe WSRESTful que tem uma sintaxe diferenciada em sua construção, mas internamente é convertida em diversas funções no momento da compilação.

Podemos então destacar as camadas de accept, de controle e negócio, até então todas em ADVPL.

02. REST tlppCore

Este é o novo modelo de REST que é mantido pelo time de Tecnologia.

Ele também é dividido nas 3 camadas destacadas na seção anterior, mas agora utiliza recursos mais modernos.

Com foco em performance, a camada de Accept é feita no binário e foi construída em C++.

Com foco em segurança, a camada de Controle é feita em TLPP, com a devida separação de recursos públicos e privados em cada componente através do encapsulamento. Inclusive seus fontes ficam em um repositório separado, chamado tlpp.rpo.

Com foco em modernização, a camada de Negócio é feita em TLPP, onde podem ser utilizados recursos como Annotation, Namespace, Nomes longos(tamanho de variáveis, funções, classes, propriedades e métodos é de 255 caracteres) e todas as novidades da nova linguagem.

03. REST 2.0

Chamamos de REST 2.0 o modelo que vai substituir o REST ADVPL e ele é mantido por ambos os times de Tecnologia e Framework, dependendo apenas de onde ocorrer a situação relatada, ou seja, em qual camada for a ocorrência.

Esse modelo utiliza as camadas:

• Accept do binário
• Controle do tlppCore
• Negócio híbrido:
• API ADVPL com as classes WSRESTFul, para manter compatibilidade.
• API TLPP com as Annotations, para novas API’s modernas.

O detalhe aqui é que independentemente do tipo de API, os recursos de ambiente pré carregado, de autenticação do Protheus e de modelos de licenciamento, estão disponíveis.

O objetivo é ganhar todos os benefícios do modelo mais moderno, mas também manter o máximo de compatibilidade que for possível para não quebrar nada que já esteja construído. Porém algumas pequenas mudanças de comportamento são necessárias para não prejudicar a performance e nem a facilidade de evoluir os recursos. Algumas mudanças que estão mapeadas:

• Página de 404 Not Found em HTML ao invés do retorno em Json;
• Barras extras no endereço das requisições não são mais desconsideradas e provocam o retorno de status 404;
• Versão 2 do SSL (Chave SSL2) descontinuada.
• Alguns cabeçalhos informativos como FWRESTBUILD que não é mais enviado.
• O mecanismo que mantinha a camada de accept em execução não fica mais em loop em uma thread ADVPL. Agora ela é executada a cada ciclo de refreshrate do [ONSTART] do AppServer e termina a execução após se certificar que o serviço de accept está respondendo. Essa mudança causa a escrita de mensagens extras no console, indicando que o job foi executado pelo refreshrate. Ela não está relacionada e nem exige nenhuma mudança de configuração no arquivo ini, ela ocorreu apenas por conta da mudança de arquitetura que o modelo sofreu.

• O REST 2.0 agora sempre devolve o header Content-Type com o valor do encode utf-8. Caso seja recebido na requisição ao servidor do REST 2.0 o header Accept , com o conteúdo charset=cp1522 este será o retorno do Content-type da requisição. Exemplo:

Com a substituição das camadas de accept e de controle já foi possível notar uma performance de resposta de requisição até 3x mais rápida com relação ao modelo ADVPL. Porém é importante ressaltar que o tempo de resposta depende muito do tipo de processamento que cada API realiza e que o ganho automático de performance se refere apenas ao tempo de pré-processamento da requisição. Com a substituição gradativa das API’s para o TLPP poderemos ter as respostas ainda mais performáticas, dependendo apenas da boa utilização da linguagem e da arquitetura adotada em cada API.

Considerações sobre como e quando utilizar cada tipo de REST

O REST ADVPL é habilitado exclusivamente através da configuração do arquivo ini do AppServer através da chave [HTTPV11] que é lida pela função HTTP_START que é executada por um job disparado pelo recurso de OnStart do servidor.

A documentação completa do REST ADVPL está disponível no TDN através do seguinte endereço: https://tdn.totvs.com/display/framework/REST+ADVPL 

A forma mais simples de identificar qual das duas versões está em execução, é observando a mensagem que é exibida no console no momento da inicialização:

Porém, caso não seja possível olhar o console, também é possível verificar a versão através do cabeçalho da resposta de qualquer requisição, pois no REST ADVPL era enviado o cabeçalho FWRESTBUILD, e a ausência desse header também indica que está com o serviço atualizado. Um endpoint simples que pode ser usado nesse teste poderia ser o /healthcheck.

A documentação sobre a configuração do REST continua sendo a mesma, disponível em https://tdn.totvs.com/pages/viewpage.action?pageId=185747842

Independentemente se estiver utilizando a versão ADVPL ou a 2.0, a intenção de uso nesse caso é a criação/utilização de API’s que acessam recursos do Protheus.

Sua autenticação(seja ela basic ou bearer) é baseada nos usuários cadastrados no Protheus, assim como o controle de tenantId baseado nas empresas cadastradas no Protheus. Sendo assim, um serviço de REST sempre está relacionado com a preparação e abertura de um ambiente com empresa e filial do Protheus.

O REST tlppCore por outro lado, é um recurso agnóstico e pode ser utilizado sem qualquer vínculo com um ambiente Protheus.

Sua configuração pode ser realizada via código ADVPL e/ou TLPP e executada da forma em que for desejado ou também pode ser realizada através de configuração no arquivo ini do AppServer.

A documentação completa sobre o REST tlppCore está disponível no TDN através do seguinte endereço https://tdn.totvs.com/display/tec/Rest

A intenção de uso nesse caso é a criação/utilização de API’s que não carregam a necessidade de utilizar recursos do Protheus. Por isso ele possui o seu próprio controle de autenticação que deve ser implementado para utilização.

Ele pode ser considerado como uma opção descolada do sistema, como seria a criação de API’s com Node.js, por exemplo.

Resumindo então os modelos e os recursos de ambiente disponíveis temos a seguinte tabela:

REST MPP

Apenas para não causar confusões em análises ou discussões futuras, vale ser mencionado aqui que existe também uma instância de REST em execução na “porta única”, mais conhecida como Multi Protocol Port (MPP).

Esse caso foi tratado por último e de forma separada pois ele não representa um modelo de REST para ser considerado como opção disponível para uso.

Essa instância utiliza o modelo 2.0 e é executada apenas quando a MPP está ativa e existe a configuração da chave App_Environment na seção [General]. Sua utilização é exclusiva para as requisições dos aplicativos Po-ui embarcados no menu do Protheus e caso receba requisições de aplicações externas deverá apresentar erro de CORS propositalmente.

Conclusões

As novidades com relação ao REST do Protheus são bem completas e irão proporcionar uma evolução tecnológica tanto no modo de escrita de API’s como também na sua utilização.

Com mais esse passo estamos caminhando para criarmos sistemas cada vez mais desacoplados, com as arquiteturas e tecnologias mais modernas no mercado.