01. Web Services REST/Server - Tecnologia - TDN http://tdn.totvs.com/pages/viewpage.action?

pageId=75268866

Tecnologia / / REST

01. Web Services REST/Server

Criado por Eduardo Perusso Riera, ltima alterao por Fabio de Moraes Rocha em 25 mar, 2015

Uma vez configurado e habilitado, deve-se codificar uma classe especial da linguagem AdvPL, o comando WSRESTFUL, que
constituir o servio.

Abrangncia
ERP 11 e superiores

Viso Geral
Para codificao de um Web Services REST, foram criadas na linguagem AdvPL instrues especiais de declarao de
classes, especficas, que suportam nomes de classe, mtodos e propriedades. A utilizao destes comandos exige a declarao da
#INCLUDE "RESTFUL.CH", no incio do cdigo fonte, como tambm ateno a alguns pontos e particularidades, comeando pela
nomenclatura do servio, estruturas, mtodos e propriedades.

Caractersticas operacionais do ambiente

muito importante estar atento ao desenvolver os mtodos REST, devido s caractersticas operacionais do ambiente de Working
Threads.
Ao executar um mtodo REST, o ambiente ser mantido no ar, aguardando uma nova requisio de processamento, de qualquer
servio ou mtodo de qualquer cliente. Desta forma, ao desenvolver um servio, no deve-se deixar queries abertas , filtros setados
em tabelas ou configuraes especficas no-padro do ambiente, realizadas para o processamento de um mtodo especfico; pois
isto pode causar impacto no funcionamento de todos os Web Services compilados e ativos neste servidor, com efeitos imprevisveis.

Nomenclatura dos servios

O nome de uma classe REST, deve ser iniciada por um caractere alfabtico e deve conter apenas os caracteres alfabticos
compreendidos entre A e Z, os caracteres numricos compreendidos entre 0 e 9, podendo tambm ser utilizado o caracter "_"
(underline). Um servio no pode ter o nome de uma palavra reservada, da linguagem AdvPL, ou ter o nome igual a um tipo bsico de
informao.
O nome da classe REST o mesmo utilizado na URI, desta forma, deve-se respeitar a estrutura de nomes permitidos na mesma.

Nomenclatura das propriedades, parmetros e retorno

Cada parmetro e retorno de todos os mtodos de um servio, devem ser declarados como uma propriedade da classe do servio,
utilizando o comando WSDATA.
A regra de nomeao dos parmetros segue o mesmo padro da nomenclatura dos servios, visto acima. Parmetros REST so
passados atravs QueryString, utilizando o mesmo nome de parametro que o declarado no servio. O Framework REST admite
n parmetros de entrada.
Para os parmetros passados atravs de EndPoint, isto : /Resources/{id}, o Framework REST disponibiliza a
propriedade AURLPARMS. Esta propriedade definida com um Array e contm todos os dados passados aps o nome do recurso
REST.
O retorno de um recurso REST deve ser sempre do tipo STRING. Um recurso REST deve ser desenvolvido tendo dois formatos de
retorno (JSON ou XML). Para consultar o retorno esperado pelo requisitante do servio, verifique o contedo da propriedade cFormat.
Esta propriedade contm os valores JSON ou XML.

Tipos bsicos de dados

So considerados e suportados, pelo TOTVS | Application Server, quando da declarao dos parmetros e retorno, os seguintes tipos
bsicos:

Tipo Descrio

String Dado AdvPL do tipo string.

Date Dado AdvPL do tipo data.

1 de 2 18/04/2017 16:03
01. Web Services REST/Server - Tecnologia - TDN http://tdn.totvs.com/pages/viewpage.action?pageId=75268866

Tipo Descrio

Integer Dado AdvPL do tipo numrico (apenas nmeros inteiros).

Float Dado AdvPL do tipo numrico (pode conter nmeros inteiros e no-inteiros).

Boolean Dado AdvPL do tipo booleano (lgico).

Base64Binary Dado AdvPL do tipo string binria, aceitando todos os caracteres da tabela ASCII, de CHR(0) CHR(255).

Tratamento de erro
Dada a natureza envolvida no processamento REST, a rotina de tratamento de erro prev o tratamento de ocorrncias, desde
advertncia de carga dos servios, falhas de inicializao de ambiente, passando por erros que invalidam um determinado servio
compilado, at as ocorrncias de inconsistncia de parmetros de chamada do servio, inconsistncia de retorno, ocorrncias de erro
fatal de processamento na aplicao e ocorrncias de processamento que no constituam um erro fatal, porm devem retornar um
pacote de ocorrncia de erro, conhecido por REST FAULT.
Portanto, no necessrio a implementao de rotinas de tratamento de erro nos mtodos REST, porm se faz necessrio a
verificao de erros de chamada do mtodo REST, tais como: Valores errados, ausncia de parametros ou dados, etc...
Para gerar um REST FAULT, deve-se utilizar a funo SetRestFault. Esta funo faz o tratamento adequado de erro e comunica ao
requisitante.

2 pessoas gostam disto

2 de 2 18/04/2017 16:03