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 ehFixo (Lógico). Por fim, vamos adicionar o relacionamento 1 to N (destaque 1 da figura 1) entre a classe Cliente e a classe Telefone.

Figura 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.1 - 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.1) 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), escolher o modelo de formulário CRUD Web na nova janela e avançar até finalizar.

Repita o procedimento 2 na classe Telefone.

Veremos a seguir como disponibilizar serviço REST via Bloco de programação e depois via Fonte de dados.

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). Siga os passos abaixo.

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

• Clique com o botão direito na pasta Servidor e no menu de contexto escolha Novo > Bloco de Programação;
• Na janela Novo vamos selecionar "Bloco de Programação Vazio (Low-code)", clicar em Avançar, preencher os campos abaixo 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 passará como argumento para a função o identificador do cliente. Clique na engrenagem da função Cliente (destaque 1 da Figura 2.1), arraste o bloco nome de entrada para dentro do bloco entradas e altere o nome da entrada para idCliente (destaque 2). Ele ficará disponível na categoria Variáveis (destaque 3).

Figura 2.1 - 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.2) e configure-o conforme os passos abaixo.

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

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

Propriedades do bloco

Agora precisamos alterar as propriedades do bloco de programação, clique na engrenagem Configuração dos tipos de regras (lado direito/superior) para abrir a janela de Propriedades do bloco de programação (Figura 2.3). Nessa janela, é importante entender os campos que estão descritos abaixo:

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

Figura 2.3 - Configuração da chamada REST

1. Mantenha o tempo limite configurado com o valor padrão, 300 segundos.
2. Selecione a opção Externa no campo Tipo.
3. No campo Segurança, clique no botão "..." e altere as permissões Permitir Executar e Permitir Obter para a opção Todos;
4. Copie o endereço do campo Cliente, ele será utilizado para testar o serviço.

Por fim, vamos salvar tudo, executar a aplicação, pois 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. Ele não será utilizado nesse tutorial, mas explicaremos nesse tópico extra.

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" (identificador do cliente), 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 4 da Figura 2.3), 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.4 - Obtendo parâmetros via Rotas e Query string

Via Fonte de dados

Vamos iniciar criando uma Fonte de dados, clique no ícone da Fonte de Dados e na janela Buscar Fonte de Dados clique no botão Nova fonte de dados (Figura 3).

Figura 3 - 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.1 - 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. Entidade: clique no botão e selecione a entidade Telefone.
4. 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.2).
5. Parâmetros: após salvar a consulta, o parâmetro aparecerá. Não é necessário definir nenhum valor. Ele será usado na consulta e passado 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.

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.2 - 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