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. 

A regra de nomeação dos parâmetros segue o mesmo padrão da nomenclatura dos serviços, visto acima. Parâmetros REST são passados através QueryString, utilizando o mesmo nome de parametro que o declarado no serviço. O Framework REST admite n parâmetros de entrada.

Para os parâmetros passados através de EndPoint, isto é: /Resources/{id}, o Framework REST disponibiliza a propriedade AURLPARMS. Esta propriedade é definida com um Array e contém todos os dados passados após 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 serviço, verifique o conteúdo da propriedade cFormat. Esta propriedade contém os valores JSON ou XML.

Tipos básicos de dados