Abrangência

ERP 11 e superiores

Visão Geral

Para codificação de um Web Services REST ADVPL, foram criadas na linguagem AdvPL instruções especiais de declaração de classes, específicas, que suportam nomes de classe, métodos e propriedades. A utilização destes comandos exige a declaração da #INCLUDE "RESTFUL.CH", no início do código fonte, como também atenção a alguns pontos e particularidades, começando pela nomenclatura do serviço, estruturas, métodos e propriedades.

Características operacionais do ambiente

É muito importante estar atento ao desenvolver os métodos REST, devido às características operacionais do ambiente de Working Threads.

Ao executar um método REST, o ambiente será mantido no ar, aguardando uma nova requisição de processamento, de qualquer serviço ou método de qualquer cliente. Desta forma, ao desenvolver um serviço, não deve-se deixar queries abertas , filtros setados em tabelas ou configurações específicas não-padrão do ambiente, realizadas para o processamento de um método específico; pois isto pode causar impacto no funcionamento de todos os Web Services compilados e ativos neste servidor, com efeitos imprevisíveis.

Nomenclatura dos serviços

O nome de uma classe REST, deve ser iniciada por um caractere alfabético e deve conter apenas os caracteres alfabéticos compreendidos entre A e Z, os caracteres numéricos compreendidos entre 0 e 9, podendo também ser utilizado o caracter "_" (underline). Um serviço não pode ter o nome de uma palavra reservada, da linguagem AdvPL, ou ter o nome igual a um tipo básico de informação.

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, parâmetros e retorno

Cada parâmetro e retorno de todos os métodos de um serviço, devem ser declarados como uma propriedade da classe do serviço, utilizando o comando WSDATA. 

...

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 serviço, verifique o conteúdo da propriedade cFormat. Esta propriedade contém os valores JSON ou XML.

Tipos básicos de dados

#INCLUDE "TOTVS.CH"
#INCLUDE "RESTFUL.CH"
 
WSRESTFUL Users DESCRIPTION "Classe Users"
 
WSDATA cResponse   AS STRING
WSDATA Count      AS INTEGER OPTIONAL
WSDATA StartIndex AS INTEGER OPTIONAL 
 
 
WSMETHOD GET DESCRIPTION "GET" WSSYNTAX "/Users/{Id} "
WSMETHOD POST DESCRIPTION "POST" WSSYNTAX "/Users/{Id} "
WSMETHOD PUT DESCRIPTION "PUT" WSSYNTAX "/Users/{Id} "
WSMETHOD DELETE DESCRIPTION "DELETE" WSSYNTAX "/Users/{Id} "
 
 
END WSRESTFUL