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

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

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

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

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

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

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

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. 

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:

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:

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:

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.