Produto:

ADVPL

Ocorrência:

Gostaria de um material que explicasse realmente como implementar a tecnologia RESTFul no Protheus, com exemplos de APIs, exemplos de programas externos consumindo o serviço, e exemplos de envio e recebimento de dados. 

Passo a passo:

A web é amplamente utilizada e reconhecida principalmente por sua arquitetura robusta, escalável e tolerante a falhas. Quem sustenta esses fatores e lhe dá todo este poder é o protocolo HTTP (o protocolo HTTP é utilizado, em regra, quando se deseja evitar que a informação transmitida entre o cliente e o servidor seja visualizada por terceiros, como, por exemplo, no caso de compras online.). Atualmente, muitas vezes necessitamos integrar aplicações em ambientes totalmente diferentes e os WebServices são uma das maneiras mais comuns e fáceis de integrar os diferentes sistemas. Este post mostrará um pouco de um modelo de WebService chamado REST.

Representational State Transfer ou somente REST, é cada vez mais usado como alternativa ao “já antigo” SOAP onde que a principal crítica a esta é a burocracia, algo que REST possui em uma escala muito menor.
REST é baseado no design do protocolo HTTP, que já possui diversos mecanismos embutidos para representar recursos como código de status, representação de tipos de conteúdo, cabeçalhos, etc.

O principal nesta arquitetura são as URLs do sistema e os resources (resource é um recurso, entidade). Ele aproveita os métodos HTTP para se comunicar, que são:

GET: Solicita a representação de um determinado recurso. É definido como um método seguro e não deve ser usado para disparar uma ação (remover um usuário, por exemplo);

POST: As informações enviadas no corpo (body) da requisição são utilizadas para criar um novo recurso. Também é responsável por fazer processamentos que não são diretamente relacionados a um recurso.

DELETE: Remove um recurso.

PUT: Atualiza um recurso na URI especificada. Caso o recurso não exista, ele pode criar um. A principal diferença entre POST e PUT é que o primeiro pode lidar não somente com recursos, mas também pode fazer processamento de informações.

Agora que já entendemos um pouco sobre o que é um webservice rest, “vamos por a mão na massa” e desenvolver uma aplicação “Hello Word REST”.

O primeiro passo para criarmos um serviço REST é configurar o Protheus como um servidor HTTP REST. Para isso vamos manipular o arquivo .ini do AppServer, conforme exemplo abaixo:

A função HTTP_START que prepara o AppServer como servidor HTTP para REST, necessitando ser configurada na seção ONSTART:

[GENERAL]

MAXSTRINGSIZE=10

[ONSTART]

JOBS=HTTPJOB

REFRESHRATE=120

[HTTPJOB]

MAIN=HTTP_START

ENVIRONMENT=P12LOCAL

Habilitando o servidor HTTP para REST:

[HTTPV11]
Enable=1

Sockets=HTTPREST

Obs: A chave Sockets referencia a(s) seção(ões) com a configuração de porta e URL que a mesma irá atender, permitindo que o Application Server seja configurado com mais de uma porta HTTP do REST:

[HTTPV11]
Enable=1

Sockets=HTTPREST,HTTPREST2

Configuração do(s) socket(s) definidos na seção HTTPV11:

[HTTPREST]
Port=8080

IPsBind=

URIs=HTTPURI

Security=0

A chave URIs referência a(s) seção(ões) com a configuração da URL que a porta irá atender, permite também que seja configurado com mais de uma URL:

[HTTPREST]
Port=8012

IPsBind=

URIs=HTTPURI,HTTPURI2

Security=1

Configuração da(s) seções URIs:

[HTTPURI]
URL=/rest

PrepareIn=99,01

Instances=1,1

Essa parte da configuração está exatamente como descrito na documentação oficial no TDN.

Após a configuração, o appserver.ini deverá ficar da seguinte maneira:

Após a adição das seções no .ini, deve reiniciar o appserver e podemos ver no log que está no ar nosso servidor http/rest:

Com nosso servidor web no ar, vamos acessar via navegador a URI que configuramos no .ini, para ter 100% de certeza que estamos prontos para “por a mão na massa”. Para acessar nossa URI, devemos acessar o caminho definido via navegador. Nesse caso, (exemplo acima) a URL que vamos acessar para testar nossa URI é a seguinte:

http://localhost:8012/rest

Deverá ser exibida a seguinte tela:

Onde nada mais é que uma página WEB contendo todas as API’s rest que está disponível no ERP Protheus.

“Pondo a mão na massa”

A nossa primeira API rest do advpl, vamos fazer um programa para retornar a descrição, unidade de medida e o status de um determinado produto.

Passo 01: Includes

Para criar um webservice REST no Protheus, precisamos da utilização de um include específico, esse include possui alguns DEFINES que facilita muito o desenvolvimento da nossa funcionalidade. Esse include é o RestFul.CH.

#Include 'Protheus.ch'
#Include 'FWMVCDEF.ch'
#Include 'RestFul.CH'

User Function EREST_01()
Return

Acima definimos uma User Function, porém ela serve apenas com “Dummy Function” (Função fantasma) ou seja, ela serve apenas para reservarmos o nome do nosso “.prw” dentro do repositório, é claro que nada te impede de utilizar essa “Dummy function” como uma função de processamento chamada no nosso programa ADVPL.

Passo 02: Definição da estrutura do WebService

Para criarmos um webservice, precisamos definir a estrutura do mesmo, ou seja, os atributos e métodos que iremos disponibilizar.

Nesse nosso primeiro exemplo, como citado acima, vamos falar apenas do método GET (método responsável por retornar informações, se estivéssemos tratando de um CRUD esse “cara” seria o Ready).

WSRESTFUL PRODUTOS DESCRIPTION "Serviço REST para manipulação de Produtos"

WSDATA CODPRODUTO As String

WSMETHOD GET DESCRIPTION "Retorna o produto informado na URL" WSSYNTAX "/PRODUTOS || /PRODUTOS/{}"

END WSRESTFUL

Entendendo o trecho de código acima:

Linha 1:

WSRESTFUL -> Início da declaração da estrutura do Webservice;
PRODUTOS -> Nome do webservice
DESCRIPTION -> Descrição do serviço

Logo após definirmos a criação do webservice, deveremos definir quais atributos o mesmo terá.

Linha 3:

WSDATA -> Definição dos atributos

No nosso caso, teremos um único atributo que é o CODPRODUTO e esse atributo é do tipo string, porém ele poderia ser:

• Float
• Boolean
• String
• Array
• Integer

Linha 5:

WSMETHOD -> Definição de um método
GET -> Define qual o tipo do método que estamos criando, podendo ser

• GET
• POST
• UPDATE
• DELETE

DESCRIPTION -> Descrição do método.
SYNTAX -> Sintaxe HTTP da chamada REST. Esta informação é utilizada na documentação do REST.

Linha 6:

END WSRESTFUL -> Encerra a declaração da estrutura do webservice.

Passo 03: Definição do método.

A definição do método é o passo onde vamos desenvolver toda a regra de negócio do método. Como nosso método é um GET, deveremos devolver um JSON para a aplicação CLIENT. Para a criação do JSON que vamos devolver para o Client, iremos utilizar a função FWJsonSerialize, veremos mais a frente sua utilização.

WSMETHOD GET WSRECEIVE CODPRODUTO WSSERVICE PRODUTOS
Local cCodProd := Self:CODPRODUTO
Local aArea := GetArea()
Local oObjProd := Nil
Local cStatus := ""
Local cJson := ""

::SetContentType("application/json")

DbSelectArea("SB1")
SB1->( DbSetOrder(1) )
If SB1->( DbSeek( xFilial("SB1") + cCodProd ) )
cStatus := Iif( SB1->B1_MSBLQL == "1", "Sim", "Nao" )
oObjProd := Produtos():New(SB1->B1_DESC, SB1->B1_UM, cStatus)
EndIf

cJson := FWJsonSerialize(oObjProd)

::SetResponse(cJson)

RestArea(aArea)
Return(.T.)

Entendendo o trecho de código acima:

Linha 1:

WsMethod -> Indica a iniciação de escrita do método
GET -> Tipo do método (Podendo ser GET, POST, UPDATE e DELETE).
WSRECEIVE -> Indica os parâmetros que iremos receber, no nosso caso, iremos receber o código de produtos via URL (Request Get), mas poderíamos receber também um JSON Object (Request POST).
WSSERVICE -> Indica o nome do webservice ao qual esse método pertence, no nosso caso o nome é PRODUTOS.

Abaixo temos a declaração das variáveis que iremos utilizar, onde no nosso caso, temos 2 que requer nossa atenção, que são as seguintes:

cCodProd -> Armazena o código do produto informado na URL.
oObjProd -> Classe que iremos criar para serializar o nosso json;

Linha 9:

Definição do tipo de retorno:

::SetContentType(“application/json”)

Após a definição do tipo de retorno, possuímos um pequeno trecho de código que nos serve para posicionar no produto que recebemos pela URL e iremos serializar o mesmo.

Para serializar o nosso registro JSON, devemos criar uma classe com os atributos que iremos retornar e alimentar os atributos com os valores desejados.

Linha 18:

Após alimentarmos o objeto criado com os atributos que queremos retornar, então devemos utilizar a função FWJsonSerialize que retorna a string do objeto passado como parâmetro.

cJson := FWJsonSerialize(oObjProd)

Linha 20:

Seta a resposta para a aplicação Client

::SetResponse(cJson)

Agora vamos ver a nossa aplicação na prática:

Feito toda a codificação do nosso exemplo e compilado no RPO, vamos verificar se o nosso WS Rest está disponível para utilização através do nossa URI:

Agora iremos realizar o “consumo” da API Rest criada através da ferramenta Postman ou no nosso caso como se trata de uma API aberta e sem nenhum tipo de autenticação, também pode ser chamado direto pela URL no navegador:

Teste pelo Postman:

Teste pelo Navegador: