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 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 link bloco de programação;
4. Saber criar uma fonte de dados, caso haja dúvidas acesse o link 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 . Em seguida, vamos adicionar a classe Telefone com os atributos id (inteiro), numero (Texto) e fixo  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.

Image RemovedImage Added

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.

Image RemovedImage Added

Figura 1.2 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.21) 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 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.1). Siga os passos abaixo.

Image RemovedImage Added

Figura 2 .1 - 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 retornará os dados de um passará como argumento para a função o identificador do cliente. Clique na engrenagem da função Cliente (destaque 1 da Figura 2.21), 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).

Image RemovedImage Added

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

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

Image RemovedImage Added

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

1. Clique na engrenagem do bloco Abrir consulta;Na janela Configurar Bloco de Programação 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

Após configurar o parâmetro REST, vamos Agora precisamos alterar as propriedades do bloco . Vamos clicar 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.43). 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:

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

1. :
   • Interno: o bloco só é consumido

1. • dentro do projeto;
   • Externo: permite que o bloco seja também consumido fora do projeto

1. • .
2. Segurança: Abre outra janela que nos permite dar autorização de CRUD e Execução aos permissionáveis do sistema.
3. 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.

Image RemovedImage Added

Figura 2.4 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.Após clicar na engrenagem, altere o campo Tipo para Externa;
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. Observe Copie o endereço do campo Endereço REST Cliente, ele será utilizado para testar o serviço.

Por fim, vamos salvar tudo, executar a aplicação e , 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. Como ele Ele não será utilizado nesse tutorial, mas se trata de um tópico que está relacionado, vamos apenas explicá-loexplicaremos 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/RESTrest/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 4 da Figura 2.43), 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-codeImage Removed

Image Added

Figura 2.5 4 - 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.

Image Removed

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.

Image Removed

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.

Image Removed

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.

Image Removed

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. 

Image Removed

Teste do serviço via Bloco

Para testar e demostrar os resultados desse tutorial usaremos a aplicação Insomnia, mas existem diversas opções como: Postman, ReqBin e outras.

Antes de partir para os próximos passos, é necessário que os dados estejam cadastrados. Por isso, rode a aplicação, abra no navegador Web e cadastre alguns clientes e telefones. 

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 (destaque 4 da Figura 2.3). 

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-11-213-49431.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.: 1.

O endereço REST completo ficará: https://app-11-213-49431.ide.cronapp.io/api/cronapi/rest/WebServiceRest:Cliente/1

Assim, abra o seu cliente de teste Rest, informe o verbo GET (destaque 1 da figura 2.5), informe o endereço da requisição (2) e clique no botão 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 será exibido através de uma lista de objetos em formato JSON (3).

Image Added

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

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

Image Added

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.

Image Added

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 configure os campos com a regra (conforme a Figura 2.2):
   t.cliente.id = :clienteId 
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.

Image Added

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.

Teste do serviço via Fonte de dados

Para testar e demostrar os resultados desse tutorial usaremos a aplicação Insomnia, mas existem diversas opções como: Postman, ReqBin e outras.

Antes de partir para os próximos passos, é necessário que os dados estejam cadastrados. Por isso, rode a aplicação, abra no navegador Web e cadastre alguns clientes e telefones. 

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 Identificador (destaque 6 da Figura 3.1). 

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

<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.1). Ex.: TelefonesCliente;
• Parâmetro: idCliente (obtido através da lista de parâmetros, destaque 5 da Figura 3.1);
• 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.: 1.

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

Assim, abra o seu cliente de teste Rest, informe o verbo GET (destaque 1 da figura 3.4), informe o endereço da requisição (2) e clique no botão Send. Fontes de dados seguem o padrão OData, dessa forma, o resultado da requisição vem no formato XML (3).

Image Added

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

Recursos privados

Nos exemplos acima apresentamos como disponibilizar recursos públicos, dessa forma, qualquer usuário que possua o endereço poderá obter os dados. Veremos agora como tornar esses mesmos recursos privado, ou seja, para obter os dados o usuário precisar ter acesso ao sistema (login e senha) e possuir a mesma permissão de segurança do recurso.

Restrição via bloco

Para tornar o recurso Rest via Bloco de programação privado, basta acessar as propriedades do Bloco de programação (passo no exemplo acima) e na propriedade Segurança (destaque 1 da figura 4), definir o permissionável para cada verbo HTTP. Nesse exemplo deixaremos todos os verbos com autorização para o permissionável "Autenticado".

Image Added

Figura 4 - Restringindo o acesso ao bloco de programação

Restrição via Fonte de dados

Para tornar o recurso Rest via Fonte de dados privado, basta acessar a aba Ações (passo no exemplo acima) e na coluna Segurança (destaque 1 da figura 4.1), definir o permissionável para cada Ação. Nesse exemplo deixaremos todos os verbos com autorização para o permissionável "Autenticado".

Image Added

Figura 4.1 - Restringindo o acesso a Fonte de dados

Teste dos recursos privados

Para acessar recursos privados nos projetos Cronapp será necessário obter um token de autorização e, em seguida, fazer a requisição utilizando esse token. 

Obter e atualizar o token

Por padrão, o token de acesso é válido por 3600 segundos, mas é possível alterar esse tempo no campo Expiração do Token (segundos) na janela de Configurações do projeto (aba Configurações do projeto). Enquanto o token estiver válido, é possível realizar diversas requisições utilizando o mesmo token.

Para obter o token, é necessário realizar uma requisição POST passando o usuário e senha no corpo da requisição. 

Image Added

Figura 4.2 - Obtendo o token da requisição

1. Defina a requisição como POST.
2. Informe o endpoint: <Domínio>/auth
Ex.: https://app-11-213-49671.ide.cronapp.io/auth
3. Configure o corpo da requisição como "Form URL Encoded".
4. No primeiro campo do corpo da requisição informe "username" e o seu valor, nesse exemplo usamos "admin".
5. No segundo campo do corpo da requisição informe "password" e o seu valor, nesse exemplo usamos "admin".
6. Execute a requisição.
7. A requisição retornará diversos dados do usuário, porém o que precisamos é do atributo token.

Antes de finalizar o tempo de expiração do token, será necessário fazer uma nova requisição para obter uma atualização do mesmo. A requisição deve ser feita no formato abaixo:

Image Added

Figura 4.3 - Requisitando a atualização do token de acesso

1. Defina a requisição como GET.
2. Informe o endpoint: <Domínio>/auth/refresh
Ex.: https://app-11-213-49671.ide.cronapp.io/auth/refresh
3. Configure um campo para o cabeçalho da requisição.
4. No campo do cabeçalho da requisição informe "X-AUTH-TOKEN" e o token obtido no passo anterior (destaque 6 da figura 4.3).
5. Execute a requisição.
6. A requisição retornará diversos dados do usuário, porém o que precisamos é do atributo token.

Requisição via Bloco privado

A requisição do Bloco de programação privado deve seguir o padrão abaixo:

Image Added

Figura 4.4 - Obtendo dados de uma requisição privada via Bloco de programação

1. Defina o verbo da requisição (exemplo GET).
2. Informe o endpoint da requisição.
   
3. Configure um campo para o cabeçalho da requisição.
4. No campo do cabeçalho da requisição informe "X-AUTH-TOKEN" e o token obtido (destaque 7 da figura 4.2 ou destaque 6 da figura 4.3).
5. Execute a requisição.
6. A requisição retornará os dados solicitados.

Requisição via Fonte de dados privado

A requisição da Fonte de dados privada deve seguir o padrão abaixo:

Image Added

Figura 4.5 - Obtendo dados de uma requisição privada via Bloco de programação

1. Defina o verbo da requisição (exemplo GET).
2. Informe o endpoint da requisição.
   
3. Configure um campo para o cabeçalho da requisição.
4. No campo do cabeçalho da requisição informe "X-AUTH-TOKEN" e o token obtido (destaque 7 da figura 4.2 ou destaque 6 da figura 4.3).
5. Execute a requisição.
6. A requisição retornará os dados solicitados.