O Cronapp permite disponibilizar serviços REST por Bloco de programação ou Fonte de dados. Veremos a seguir como configurar nos dois casos. E, ao final, mostraremos como obter esses recursos usando um programa externo ao Cronapp.

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. Saber utilizar as funcionalidades do diagrama, como criar classes e gerar persistência, caso haja dúvidas acesse o link diagrama;
3. Saber criar um bloco de programação, caso haja dúvidas acesse o link bloco de programação;
4. Saber criar uma fonte de dados, caso haja dúvidas acesse o link fonte de dados.

Configurando o diagrama

Nesse tutorial vamos criar uma agenda simples utilizando um relacionamento de 1 para N, onde um cliente pode possuir vários telefones. Vamos começar criando a classe Cliente com os atributos id (inteiro) e nome (Texto), em seguida, vamos adicionar a classe Telefone com os atributos id (inteiro), numero (Texto) e fixo (Lógico). Por fim, vamos adicionar o relacionamento 1 to N entre a classe Cliente e a classe Telefone.

Figura 1.1 - Configurando o relacionamento entre classes

Após configurar as classes e o relacionamento, vamos gerar a camada de persistência e as páginas CRUD.

Figura 1.2 - Gerando o CRUD e a camada de persistência

1. Parar gerar a camada de persistência, vamos clicar no ícone (1 da Figura 1.2) e, na nova janela, clicar no botão Gerar;
2. Para gerar as páginas CRUD, vamos clicar com o botão direito do mouse sobre a entidade Cliente, selecionar Criar visão para a entidade (2) e escolher o modelo de formulário CRUD Web na nova janela. Vamos repetir o item 2 na entidade Telefone.

Via Bloco de programação

Para configurar o serviço REST via bloco, vamos iniciar criando um bloco de programação do lado Servidor (Figura 2.1). Siga os passos abaixo.

Figura 2.1 - Nova função de bloco de programação

1. Clique com o botão direito na pasta Servidor e escolher Novo;
2. Em seguida, vamos clicar em Bloco de Programação;
3. Na janela Novo vamos selecionar Bloco de Programação Vazio (Low-code), clicar em Avançar, preencher os campos e clicar em Finalizar.
   • Nome do Arquivo: WebServiceREST;
   • Nome da Função: Cliente.

Configuração

Parâmetro REST

Vamos começar a configuração criando o parâmetro idCliente que retornará os dados de um cliente. Clique na engrenagem da função Cliente (Figura 2.2), arraste o bloco nome de entrada para dentro do bloco entradas e altere o nome da entrada para idCliente. Ele ficará disponível na categoria Variáveis.

Figura 2.2 - Adicionando parâmetro de entrada à função

Agora arraste o bloco Abrir consulta (categoria Banco de dados) para que os dados sejam retornados, encaixe-o no retorno da função Cliente (Figura 2.3) e configure-o, conforme os passos abaixo.

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

1. Clique na engrenagem do bloco Abrir consulta;
2. Na janela Configurar Bloco de Programação:
   1. Selecione a entidade Telefone em "..." e clique em Adicionar;
   2. Adicione um Novo Campo e escolha a opção Obter t;
   3. Adicione uma Nova Regra e selecione t.cliente.id, o restante da expressão será preenchido de forma automática;
3. Clique em OK ao final;
4. Por fim, adicione a variável idCliente (categoria Variáveis) no parâmetro clienteId.

Propriedades do bloco

Após configurar o parâmetro REST, vamos alterar as propriedades do bloco. Vamos clicar na engrenagem Configuração dos tipos de regras (lado direito/superior) para abrir a janela de Propriedades do bloco de programação (Figura 2.4). Nessa janela, é importante entender os campos que estão descritos abaixo e, após entendê-los, seguir para os passos abaixo da Figura 2.4:

• Tempo 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 no projeto;
  2. Externo: permite que o bloco seja também consumido 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 outra janela que nos permite dar autorização de CRUD e Execução aos permissionáveis do sistema.

Figura 2.4 - Configuração da chamada REST

1. Após clicar na engrenagem, altere o campo Tipo para Externa;
2. No campo Segurança, clique no botão e altere as permissões Permitir Executar e Permitir Obter para Todos;
3. Observe o campo Endereço REST, ele será utilizado para testar o serviço.

Por fim, vamos salvar tudo, executar a aplicação e a requisição REST via bloco de programação já estará disponível. 

Informação extra

Parâmetro Query String

Também é possível obter parâmetros por query string. Como ele não será utilizado nesse tutorial, mas se trata de um tópico que está relacionado, vamos apenas explicá-lo.

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

Diferentemente dos parâmetros por Rotas, 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 Obter parâmetro da query string, conforme as informações abaixo e a Figura 2.5.

Rode o projeto, abra a aplicação no navegador Web e cole o endereço abaixo, alterando as informações conforme seu projeto:

<Domínio>/api/cronapi/REST/WebServiceREST:Cliente/3123?param1=Cronapp&param2=low-code

• Domínio: é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-30-205-11680.ide.cronapp.io;
• Endereço REST: é encontrado nas Propriedades do bloco (item 3 da Figura 2.4), contendo o nome do bloco, o nome da função e o nome de entrada definidos. Observação: Note que o <idCliente> foi passado na URI como 3123; 
• ?: separa o endereço URI dos parâmetros query string;
• Parâmetro=valor: nome do parâmetro e seu valor. Ex.: param1=Cronapp;
• & (ampersand): permite adicionar outro parâmetro=valor.

O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/REST/WebServiceREST:Cliente/3123?param1=Cronapp&param2=low-code

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

Via Fonte de dados

Vamos iniciar criando uma Fonte de dados. Acesse Projeto (Figura 3.1) no menu do sistema e selecione a opção Fonte de Dados, na janela Buscar Fonte de Dados clique no botão Nova fonte de dados.

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 e a consulta ao banco na aba Filtros.

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. Estamos utilizando TelefonesCliente;
2. Nome da consulta: nome que será exibido na lista de fonte de dados do projeto. Estamos utilizando TelefonesCliente;
3. Endereço REST: trecho final (URN) do endereço do serviço REST, será concatenado após o domínio do sistema;
4. Entidade: clique no botão e selecione a entidade Telefone;
5. Configura consulta: clique no botão para personalizar a consulta da fonte de dados. Na nova janela, clique em Nova Regra e escolha t.cliente.id (conforme a Figura 2.4);
6. Parâmetros: após salvar a consulta, o parâmetro aparecerá, não é necessário definir nenhum valor. Ele é usado na consulta e na query string do endereço.

Agora vamos configurar as permissões de acesso. Vá até a aba Ações, clique no cadeado do verbo Permitir Obter para abrir a janela Permissão de Segurança, deixe apenas a opção Todos selecionada. Repita em Permitir Filtrar e Permitir Contar.

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

Por fim, vamos salvar tudo, executar a aplicação e a requisição REST via fonte de dados já estará disponível.

Testando o serviço

Existem diversas aplicações para testar serviços REST, para demostrar os resultados desse tutorial usaremos sites externos com o método GET. Antes de partir para os próximos passos, é necessário que os dados estejam cadastrado. Por isso, rode a aplicação, abra no navegador Web e cadastre os dados que quiser nos formulários Cliente e Telefone. 

Bloco de programação

Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviço.

Endereço

Para esse tutorial vamos usar o domínio temporário gerado no debug do Cronapp (ex.: https://app-30-205-11680.ide.cronapp.io/).  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.5. 

Considere que endereço REST é formado pelos principais elementos abaixo:

<Domínio>/api/cronapi/REST/blockly.<Nome do Blockly>:<Nome da Função>[/<Parâmetro 1>[/Parâmetro N]]

• Domínio: é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-30-205-11680.ide.cronapp.io/;
• Nome do Blockly: é o arquivo Blockly ou bloco de programação. Ex.: WebServiceREST;
• Nome da Função: é o nome da função que se deseja acessar. Ex.: Cliente;
• Parâmetro: é o valor do parâmetro passado na função, nesse tutorial estamos utilizando o ID do cliente como parâmetro. Ex.: 2.

O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/rest/WebServiceRest:Cliente/2

Requisição

Vamos testar o serviço abrindo a página do ReqBin, colando o endereço REST completo no campo, selecionando o método GET e clicando em Send. 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.

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

Fonte de dados

Primeiro vamos entender como o endereço REST é formado e, em seguida, vamos testar o serviço.

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-30-205-11680.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: é o domínio da aplicação. Nesse tutorial estamos utilizando o domínio temporário. Ex.: https://app-30-205-11680.ide.cronapp.io/;
• Identificador da fonte: é o identificador da Fonte de Dados (item 1 da Figura 3.2). Ex.: TelefonesCliente;
• Parâmetro: idCliente (obtido através da lista de parâmetros, destaque 5 da Figura 3.2);
• Valor do parâmetro: é o valor do parâmetro passado na função, nesse tutorial estamos utilizando o ID do cliente como parâmetro. Ex.: 2.

O endereço REST completo ficará: https://app-30-205-11680.ide.cronapp.io/api/cronapi/odata/v2/app/TelefonesCliente?idCliente=2

Requisição

Vamos testar o serviço abrindo a página http://4alltests.com.br/testeapis/, selecionando o método GET, colando o endereço REST completo no campo Endpoint e clicando em Enviar. Requisições via fonte de dados sempre retornam uma lista de objetos em XML. 

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