O Cronapp permite disponibilizar serviços REST por Bloco de programação ou Fonte de dados. Veremos a seguir como configurar nos dois casocasos. 

Pré-requisitos

1. Projeto do tipo mobile ou web criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar projeto );
2. Criar classes no Diagrama, gerar persistência e popular o banco. Para criar classes e gerar persistência acesse o link ( Diagrama Diagrama ).
   Para esse exemplo vamos criar um agenda simples, utilizando um relacionamento de 1 para N, onde um cliente pode possuir vários telefones. (Figura 1).

Figura 1 - Relacionamento usado nesse exemplo

Passos

Veremos a seguir como configurar o serviço REST via Bloco de programação e Fonte de dados, usaremos a mesma estrutura exibida na figura 1. No final mostraremos como obter esses recursos usando um programa externo ao Cronapp. 

Via Bloco de programação

Crie um bloco de programação do lado Servidor , nesse exemplo nomearemos o bloco para e informe o nome "WebServiceRest" para o bloco e sua função para "cliente" . A função irá receber como parâmetro um identificador do cliente "idC" e retornar os dados telefônicos desse cliente.Como a função deve só retornar os dados do banco, configuramos a consulta para enviar direto no retorno da função, passando o parâmetro recebido na função que será informada no endereço da requisição. para a função (Figura 2.1)

.

Image Modified

Figura 2.1 - Configurando o Nova função de bloco de programação e consulta

Configuração do Bloco

Após finalizar criar a estrutura da função, clique na engrenagem "Configuração dos tipos de regras" (lado direito/superior) para abrir a janela de "Propriedades do bloco de programação". Nessa janela, os únicos campos que nos interessam estão descritos abaixo. (Figura 2.2)

• Tempo limite: Limite limite em segundos para a execução. Após o limite, a ação é finalizada.
• Tipo: define o tipo de permissão para acesso ao bloco, sendo dois tipos:
  1. Interno: o bloco só é consumido dentro do projeto;
  2. Externo: permite que o bloco seja também consumido
  também
  1. fora do projeto;
• Endereço REST: trecho final do endereço do serviço REST, será concatenado após o domínio do sistema;
• Segurança: Abre uma outra janela que nos permite dar autorização de CRUD e Execução a diferentes perfis de segurançaaos permissionáveis do sistema.

Autorize para "Altere o campo Tipo para "Externo" e autorize, selecionando a opção "Todos", os campos : "Permitir Executar" e " e Permitir Obter" na  na janela de Segurança. Altere também o campo Tipo para "Externo".  (Figura 2.2)

Figura 2.2 - Configuração da chamada REST

Finalizada a configuração do bloco, podemos obter parâmetros por REST ou Query String. Usaremos nesse tutorial a opção REST, porém mostraremos também como obter por Query String.

Parâmetro REST

Para obter o parâmetro dessa forma, basta clicar sobre a engrenagem do bloco Função (destaque 1 da Figura 2.3), arrastar e nomear o bloco nome de entrada. Nesse tutorial só precisaremos de um parâmetro, por isso, arraste um bloco e nomeio para "idC" (identificador do Cliente). Podemos adicionar quantos parâmetros forem necessários, eles ficarão disponíveis no menu lateral Variáveis (destaque 2 da Figura 2.3).

Image Added

Figura 2.3 - Adicionando parâmetros de entrada à função

Ao utilizar parâmetros Rest, não é necessário que o requerente saiba o nome exato dos parâmetros, porém, é fundamental que saiba a ordem exata que esses parâmetros devem ser passados após o nome da função. Por exemplo, se além da entrada idC, inseríssemos outra, como idOperadora, a estrutura final da URI ficaria como no trecho abaixo, onde o valor "3123" seria recebido pela variável idC e o valor "05" pela idOperadora (Figura 2.4).

https://... WebServiceRest:cliente/3123/05

Image Added

Figura 2.4 - Obtendo mais de um parâmetro

Parâmetro Query String

Os parâmetros via query string também pode ser passados junto com os parâmetros Rest, dessa forma, é possível efetuar uma requisição como no trecho da URI abaixo, em que após o parâmetro REST "3123", usamos o caractere interrogação "?" para informar os parâmetros query string e seus valores.

Diferentemente dos parâmetros Rest, não é necessário se preocupar com a ordem dos parâmetros query string definidos na URI. Para obter seus valores, basta utilizar o bloco "result", informando o nome parâmetro. (URI abaixo e Figura 2.5) 

https://... WebServiceRest:cliente/3123?param1=Cronapp&param2=low-code

• ?: separa o endereço URI dos parâmetros query string;
• Parâmetro=valor: nome do parâmetro e seu valor;
• &: (ampersand) permite adicionar outro parâmetro=valor.

Image Added

Figura 2.5 - Obtendo parâmetros via Rest e Query string

Consulta ao banco de dados

Como informado anteriormente, a função irá receber como parâmetro um identificador de cliente "idC" e retornar os dados telefônicos desse cliente. Para isso, arraste o bloco "Abrir consulta" (menu lateral > Banco de dados) e encaixe no retorno da função cliente. 

Clique no ícone de engrenagem do bloco "Abrir consulta" e configure como na Figura 2.6. Após salvar a configuração do Assistente JPQL, será exibido um parâmetro de entrada do identificador do cliente, encaixe o bloco da variável "idC".

Image Added

Figura 2.6 - Configurando o bloco de programação e consulta

Salve todas as janelas para que o Cronapp gere as anotações necessárias, Após confirmar todas as janelas e salvar, o Cronapp irá gerar as anotações necessárias e assim que a aplicação estiver em execução a requisição REST estará disponível.

Endereço

Quando o seu sistema estiver em produção e com domínio próprio (ex.: https://www.cronapp.io), utilize-o para concatenar com o endereço (URN) do serviço REST apontado no campo Endereço Rest da figura 2.2. Para esse tutorial usaremos o domínio temporário gerado no debug do Cronapp (ex.: https://app-19-33-61591.ide.cronapp.io/). 

O trecho do endereço gerado no campo Endereço REST é formado com endereço possui os seguintes elementos:

<Domínio>/api/cronapi/rest/blockly.<Nome do arquivo com a funçãoBlockly>:<nome Nome da Função>[/<Parâmetro 1>[/Parâmetro nN]]

Considerando os elementos abaixo:

• Domínio: https://app-19-33-61591.ide.cronapp.io/
• Arquivo JavaBlockly: WebServiceRest
• Função: cliente
• Parâmetro: 1 2 (valor do parâmetro passado na função)

O endereço Rest completo ficará:

https://app-19-33-61591.ide.cronapp.io/api/cronapi/rest/blockly.WebServiceRest:cliente/12

Via Fonte de dados

Crie uma Fonte de dados seguindo os seguintes passos: acesse Projeto > Fonte de dados no menu do sistema para abrir a janela Buscar Fonte de dados e clique no botão Nova Fonte de dados ao final (Figura 3.1).

Figura 3.1 - Criando nova Fonte de dados

Configuração

Com a janela da Fonte de dados aberta, vamos configurar as informações da fonte de dados, sua consulta ao banco e permissão de acesso.

Figura 3.2 - Configuração das informações da fonte e sua consulta

1. Identificador: fonte de dados que será usado na URI do serviço REST.
2. Nome da consulta: nome que será exibido na lista de fonte de dados do projeto.
3. Entidade: botão de seleção das entidades.
4. Configura consulta: personaliza a consulta da fonte de dados;
5. Parâmetros: parâmetros definidos nas regras da consultanome do parâmetro usado na consulta e na query string do endereço;
6. Endereço REST: trecho final (URN) do endereço do serviço REST, será concatenado após o domínio do sistema.

Ao clicar no botão de personalização da consulta (item 4 da figura 3.2), uma janela de personalização da consulta será aberta, configure do mesmo jeito que configuramos na figura 2.1. Após salvar a consulta, um parâmetro será apresentando apresentado na lista (item 5 da figura 3.2), não é necessário definir nenhum valor.

Após a configuração da aba Filtro, acesse a aba Permissões e clique nos cadeados dos verbos Permitir Obter, Permitir Filtrar e Permitir Contar para abrir a janela Permissão de Segurança, deixe a opção Todos selecionados em todas as janelas (Figura 3.3).

Figura 3.3 - Configuração das permissões da fonte de dados

Após salvar, execute a aplicação e a requisição REST por fonte de dados já estará disponível.

Endereço

Quando o seu sistema estiver em produção e com domínio próprio (ex.: https://www.cronapp.io), utilize-o para concatenar com o endereço (URN) do serviço REST apontado no item 6 da figura 3.2. Para esse tutorial usaremos o domínio temporário gerado no debug do Cronapp (ex.: https://app-19-33-61591.ide.cronapp.io/). 

O trecho do endereço formado no item 6 é uma query string formado com os seguintes elementos:

<Domínio>/api/cronapi/odata/v2/app/<Identificador da fonte>[?<Parâmetro 1>=<Valor do Parâmetro 1>[&<Parâmetro n>=<Valor do Parâmetro n>]]

Considerando os elementos abaixo:

• Domínio: https://app-19-33-61591.ide.cronapp.io/
• Identificador da Fonte de dados: TelefonesCliente
• Parâmetro: idCliente (obtido através da lista de parâmetros, destaque 5 da Figura 3.2)
• Valor do parâmetro: 12

O endereço Rest completo ficará:

https://app-19-33-61591.ide.cronapp.io/api/cronapi/odata/v2/app/TelefonesCliente?idCliente=12

Teste do serviço

Existem diversos diversas aplicações para testar serviços REST: Programas, extensões de navegadores e até sites. Estamos utilizando a aplicação Postman.Selecione , para demostrar os resultados desse tutorial usaremos o Postman. Para utilizá-lo, basta selecione o Verbo ou método HTTP, nesse caso estamos usando usaremos só o GET, informar o endereço completo do serviço e clique clicar em "Send" para retornar o conteúdo referente ao cliente, nesse exemplo estamos consultando o cliente que possui o identificador "2".exibir o conteúdo retornado. 

Bloco de programação

Requisições Rest de um bloco de programação pode retornar qualquer formato, porém, como estamos obtendo o conteúdo do bloco "Abrir consulta", o conteúdo é exibido através de uma lista de objetos em formato JSON. Na figura 4.1 utilizamos a URI informado no tópico Endereço do bloco de programação.

Figura 4.1 - Retorno do serviço via Bloco de programação

Fonte de dados

Requisições via fonte de dados sempre retornam uma lista de objetos em XML. Na é retornado um XML ( figura 4.2 ), no Bloco de programação (figura 4.1) é retornado um array em JSON, isso ocorre pois o bloco Abrir consulta que usamos no exemplo da figura 2.1 sempre retorna um array de objetoutilizamos a URI informado no tópico Endereço da fonte de dados.

Figura 4.2 - Retorno do serviço via Fonte de dados