Uma vez configurado e habilitado, deve-se codificar uma classe especial da linguagem AdvPL, o comando WSRESTFUL, que constituirá o serviço.
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
São considerados e suportados, pelo TOTVS | Application Server, quando da declaração dos parâmetros e retorno, os seguintes tipos básicos:
| Tipo | Descrição |
|---|---|
| String | Dado AdvPL do tipo string. |
| Date | Dado AdvPL do tipo data. |
| Integer | Dado AdvPL do tipo numérico (apenas números inteiros). |
| Float | Dado AdvPL do tipo numérico (pode conter números inteiros e não-inteiros). |
| Boolean | Dado AdvPL do tipo booleano (lógico). |
| Base64Binary | Dado AdvPL do tipo string binária, 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 ocorrências, desde advertência de carga dos serviços, falhas de inicialização de ambiente, passando por erros que invalidam um determinado serviço compilado, até as ocorrências de inconsistência de parâmetros de chamada do serviço, inconsistência de retorno, ocorrências de erro fatal de processamento na aplicação e ocorrências de processamento que não constituam um erro fatal, porém devem retornar um pacote de ocorrência de erro, conhecido por REST FAULT.
Portanto, não é necessário a implementação de rotinas de tratamento de erro nos métodos REST, porém se faz necessário a verificação de erros de chamada do método REST, tais como: Valores errados, ausência de parametros ou dados, etc...
Para gerar um REST FAULT, deve-se utilizar a função SetRestFault. Esta função faz o tratamento adequado de erro e comunica ao requisitante.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas