Páginas filhas
  • Entendendo as novidades do REST

Atenção

No Rest ADVPL, ao subir o appserver ele inicia o serviço com a quantidade de threads configuradas com inicial, através da chave instances. No REST 2.0, por enquanto, ele inicia o serviço sem nenhuma thread ativa, subindo a quantidade prevista como inicial somente após a primeira requisição.

Este comportamento tem previsão de alteração para a lib e appservers a serem disponibilizados a partir de julho de 2021.

Chuncked

O novo REST 2.0  contempla o retorno em chunked a partir da lib label 20201123

Idioma

O REST pode responder a requisição no idioma desejado, para isso é necessário enviar o header Accept-Language, sendo que somente são aceitos os idiomas que o Protheus suporta, como pt-BR, es e en. Com isso, a resposta passa a retornar o header Content-Language.

Esse recurso está disponível a partir da lib 20210628, sendo que o REST ADVPL e o REST 2.0 tem suporte a esse header.

Módulo

A partir da lib 20211116 o REST passará a receber o header x-erp-module, que representa o módulo do Protheus, esse header suporta os valores de módulos do Protheus válidos, como: FIN, EST, FAT, ATF.

Database

A partir da lib 20240115 o REST passará a receber o header x-erp-database, que representa a databas do Protheus, esse header precisa ser enviado no formato AAAAMMDD


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.


Importante

O REST 2.0, que será disponibilizado a partir da Lib 20201009, irá utilizar a mesma configuração de ini do [HTTPV11] e irá substituir a versão antiga de forma automática a partir da Release 33 do Protheus (o REST convencional em ADVPL será descontinuado neste release).

Para utilizar este recurso na lib 20201009 será necessário ligar a chave ADVPL=0 na seção [HTTPV11] .

A partir da lib label 20210809 o REST 2.0 passará a ser utilizado por default no sistema, quando o AppServer tiver na versão igual ou superior a 19.3.1.8, mas poderá ser desligado através da mesma chave.

Esta chave é temporária e a partir da release 33 do Protheus a mesma será descontinuada, sendo possível somente a configuração do novo REST 2.0.

Além do pacote de lib acima é necessário também o uso do AppServer com versão igual ou superior a 19.3.1.0.

Exemplo:

Release menor que 12.1.33Release igual ou superior a 12.1.33
ChaveLib label 20200109Lib Label 20210809
Advpl = 1REST 2.0 desligadoREST 2.0 desligadoREST 2.0 ligado
Advpl = 0REST 2.0 ligadoREST 2.0 ligadoREST 2.0 ligado
Vazia (sem a chave)REST 2.0 desligadoREST 2.0 ligadoREST 2.0 ligado



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.


Aqui há um grande detalhe que precisa ser compreendido.

O REST tlppCore não é a evolução do REST ADVPL, ele é um recurso novo, e por isso não mantém compatibilidade de recursos, como a autenticação baseada em usuário do Protheus ou a utilização automática dos ambientes, onde a thread de execução estaria com a conexão ao banco de dados já realizada e com informações de empresa e filial carregas por exemplo. Nesse caso então, não há então nenhum desses recursos automaticamente carregados.


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:



RequisiçãoResposta do REST ADVPLResposta do RestServer 2.0Encode retornado na resposta (REST ADVPL e REST 2.0)
Accept: charset=utf8Content-Type: charset=utf8Content-Type: charset=utf-8A própria lib realiza o encode para utf-8 
Accept: charset=utf-8Content-Type: charset=utf-8Content-Type: charset=utf-8A própria lib realiza o encode para utf-8
Accept: charset=cp1252Content-Type: charset=cp1252Content-Type: charset=cp1252Não é realizado encode (irá utilizar o padrão do sistema)
Accept: charset=cp1251Content-Type: charset=cp1251Content-Type: charset=cp1251Não é realizado encode (irá utilizar o padrão do sistema)
VazioVazioContent-Type: charset=utf-8Não é realizado encode na camada de lib.
Accept: charset=QualquerOutroValorContent-Type: charset=QualquerOutroValorContent-Type: charset=utf-8Não é realizado encode na camada de lib.

Importante

Para o correto tratamento de encode nas apis, sugerimos o uso da função FWhttpEncode



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.


Importante

Não confunda as configurações dos dois modelos, pois elas trabalham com chaves bem semelhantes, porém distintas. A chave principal neste modelo é a [HTTPSERVER], e a documentação desta seção e relacionadas estão disponíveis no link: https://tdn.totvs.com/pages/viewpage.action?pageId=550117647.


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:


Recurso

ADVPL

tlppCore

2.0

Todas as API’s WSRESTFul compiladas no RPO

Sim

Não

Sim

Todas as API’s com Annotations compiladas no RPO

Não

Sim

Sim

Ambiente aberto
(RpcSetEnv)

Sim

Não

Sim


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.

2 Comentários

  1. Na mensagem "a partir da Release 33 do Protheus (o REST convencional em ADVPL será descontinuado neste release)." qual seria o REST convencional? o REST MPP ou o REST ADVPL? não ficou claro qual seria o "convencional"

    1. Olá, boa tarde. O REST em advpl.