...

Visão Geral

Para codificação de

...

um Web Services REST,

...

 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.

Nomenclatura de estruturas

O nome

...

da classe REST é o mesmo utilizado na URI, desta forma, deve-se respeitar a estrutura de nomes permitidos na mesma.

Uma estrutura constitui um agrupamento de dados, criado como um comando especial (WSSTRUCT) em AdvPL. Para isso, deve-se criar de uma estrutura para um serviço, quando for necessário agrupar um conjunto de dados básicos e/ou outras estruturas em um único tipo de informação, que será utilizada como parâmetro e/ou retorno em um ou mais métodos do serviço.

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.