As Fontes de dados do tipo Web Services necessitam de algumas configurações a mais em relação aos demais tipos (Consulta a Entidade, Bloco de programação e SQL Nativo), essas configurações são necessárias para adaptar a comunicação entre a Fonte de dados e a API externa. Quando algum recurso da aplicação Cronapp necessita de algum dado, ele solicita a Fonte de dados (destaque 1 da figura 1), que por sua vez direciona essa requisição no padrão que a API externa reconheça (2), recebe uma resposta (3), trata e retorna o conteúdo ao componente que fez a solicitação (4).

Figura 1 - Fluxo de comunicação entre um componente, Fonte de dados e API

Veremos alguns exemplos de como configurar a Fonte de dados para receber recursos no padrão REST e SOAP. Para outros detalhes, acesse a documentação da Fonte de dados.

Definição inicial

De modo a simplificar os exemplos apresentados nessa documentação, vamos assumir algumas nomenclaturas para os endereços de APIs utilizadas nessa documentação.

Figura 1.1 - Exemplo de estrutura de endereço para uma API

• Domínio: endereço base onde a API está hospedada. Para essa definição, o domínio pode ou não conter subdomínios. Ex: https://subdominio.dominio.com.br
• URL base: ponto de partida comum (domínio e parte da rota) para todos os recursos de uma determinada API. Muitas APIs não possuem uma rota fixa para agrupar vários de seus recursos, nesses casos, a URL base será o próprio domínio.
• Rotas: especifica o caminho final do endereço para um recurso.
• Endpoint: é a combinação da URL base (domínio), rota e, opcionalmente, query string que define uma operação específica na API.
• Query string: define um ou mais parâmetros, no formato chave=valor, para o recurso.

Web Service - REST

Antes de criarmos uma Fonte de dados REST, precisamos ter em mãos o endpoint (verbo HTTP GET) do serviço que iremos usar e, em seguida, realizar os passos abaixo:

1. Obter campos do serviço: executa alguns passos para obter os campos do objeto.
2. Aba Ações: configura os demais métodos do serviço e seus parâmetros. Os recursos de paginação e ordenação devem ser configurados aqui.
3. Aba Campos: se necessário, é possível personalizar os campos obtidos na primeira etapa.
4. Aba Cabeçalho: se necessário, é possível configurar o cabeçalho da requisição.

Nova Fonte de dados

Para criar a Fonte de dados, acesse o Botão do menu do sistema > Fonte de dados (destaque 1 da figura 2) e após abrir a janela, clique no botão Nova Fonte de dados (destaque 2). 

Figura 2 - Criando uma Fonte de dados

Passos para obter campos do serviço

Com a janela da Fonte de dados aberta, preencha os campos Identificador e Nome da consulta, em seguida, selecione a opção Web Services (destaque 1 da figura 2.1) e informe o endereço do endpoint REST (verbo Get) no campo ao lado (destaque 2), por fim, clique no botão Obter campos do serviço (destaque 3) para abrir a janela de configuração.

Figura 2.1 - Informando o endpoint e iniciando a configuração

Durante os passos a seguir, o Cronapp tentará obter todas as informações automaticamente, necessitando apenas que o usuário avance as telas até finalizar. Os dados obtidos podem ser modificados durante ou após o processo.

Passo 1

A primeira janela exibe os campos necessários para realizar a requisição.

Figura 2.2 - Configuração da URL e Cabeçalhos

1. URL: endpoint do verbo Get que informamos no passo anterior (destaque 2 da figura 2.1).
2. Novo Cabeçalho: se o recurso REST necessita de cabeçalhos próprios, como os de autenticação (exemplos: authorization ou x-auth-token), é possível informar o nome do cabeçalho e adicioná-lo à lista clicando no ícone (+).
3. Lista de cabeçalhos: essa lista aceita apenas valores estáticos, após obter os campos, utilize a aba Cabeçalho para configurar os cabeçalhos com valores dinâmicos, 

Clique em Avançar.

Passo 2

Na próxima tela (Figura 2.3), o campo Resultado exibirá o retorno da requisição e o Cronapp tentará preencher automaticamente os dois primeiros campos. Esses campos podem ser editados posteriormente na aba Ações.

• Para Obter: esse campo deve conter o caminho JSON até o atributo que contém a lista com os objetos.  
• Para Contar: esse campo deve conter o caminho JSON até o atributo que contém o número total de registros, usado para realizar a paginação do conteúdo. 
• Resultado: retorno da requisição.

Figura 2.3 - Localizando os dados no JSON

Clique em Avançar.

Passo 3

Após identificar a lista de objetos no passo anterior, o Cronapp exibirá um objeto com todos os seus campos em Resultado (Figura 2.4). 

• Resultado: primeiro objeto da lista.
• Contagem: exibe o total de registros com base no atributo informado no campo Para Contar (Figura 2.3).
• Chaves: o Cronapp tentará identificar qual a chave do objeto, porém, clicando no campo (figura 2.4), é possível escolher, manualmente, os campos chaves. Essa configuração poderá ser feita depois na aba Campos.

Figura 2.4 - Configuração dos identificadores do objeto

Clique em Avançar.

Passo 4

A janela a seguir permite ajustar os campos já mapeados pela Fonte de dados ou adicionar Novos Campos. Informe na coluna Caminho o JSON Path do atributo que alimentará esse campo. Essa configuração poderá ser feita depois a partir da aba Campos.

Figura 2.5 - Configuração manual dos campos do serviço REST

Na maioria das vezes não é necessário realizar qualquer ação nessa janela.

Clique em Avançar.

Passo final

A última janela exibirá um objeto completo, com as configurações feitas até aqui. Clique em Finalizar para retornar as configurações da Fonte de dados.

Figura 2.6 - Resultado final

Após Finalizar, a aba Campos será exibida com todos os atributos configurados.

Obter campos com e sem metadados

Se o endpoint usado pertencer a uma Fonte de Dados (OData) de outro projeto Cronapp, e esse projeto estiver configurado com a opção "Expor Metadados" ativada nas Configurações do Projeto, ao tentar acessar o recurso, a janela Obter campos do serviço será capaz de extrair os metadados do projeto de origem. Isso permitirá acessar informações detalhadas sobre os campos, como tipos de dados, se eles aceitam valores nulos, quais são os campos chave e a definição do campo "ObjectKey".

No caso de serviços externos sem metadados, a janela Obter campos do serviço irá identificar os campos dos objetos retornados e inferir quais os tipos desses campos (exemplo: String, Boolean, Date, ...), porém, nem sempre isso é possível, nesses casos, o desenvolvedor pode ajustar esses atributos na aba Campos.

Requisição personalizada

A Fonte de dados permite criar rotas dinâmica para o endpoint e adicionar chaves query string diferentes nas requisições de cada verbo HTTP. Esses parâmetros são configuráveis na aba Filtro (acesse o tópico "Aba Filtro" da documentação Fonte de Dados).

Rotas

Para definir rotas dinâmicas a partir dos parâmetros informados à Fonte de dados, basta substituir parte do endereço (ou o endereço inteiro) pela expressão ":<parâmetro>" (dois pontos + nome do parâmetro) no endereço do endpoint (ex.: http://www.ws.com/usuario/:rotaDinamica/dados) (destaque 1 da figura 2.7), o parâmetro definido ("rotaDinamica") será criado na lista de parâmetros da aba Filtro (2). Isso permitirá que a mesma Fonte de dados faça requisições para endereços diferentes, mudando o parâmetro informado.

Vale ressaltar que os endereços montados devem ser compatíveis com as demais configurações da Fonte de dados: abas Cabeçalhos, Campos e Ações.

Figura 2.7 - Incluindo parâmetros para tornar a URL Base dinâmica

No exemplo da figura 2.7, ao executar a Fonte de dados informando um valor para o parâmetro "rotaDinamica" (ex.: post), o endpoint será montado da seguinte forma: https://meusistema.com.br/post/comentarios

Query String

Na aba Ações da Fonte de dados é possível configurar parâmetros Query String que serão incluídos nas requisições de cada verbo HTTP. Assim, após o endereço do endpoint será adicionado o caractere "?" (interrogação) para informar onde começa a lista com os parâmetros (Chave=Valor) e, entre cada parâmetro, será adicionado o caractere separador "&" (ampersand),

No exemplo da figura 2.8 foram configurados 2 parâmetros querystring para as requisições Para Obter (GET): postid e id.

O valor do parâmetro "id" (destaque 2) foi definido de forma estática, sendo assim, em todas as requisições GET dessa Fonte de dados, o valor do "id" sempre será "21". 

Figura 2.8 - Adicionando parâmetros queryString a uma requisição REST

A querystring "postId" (destaque 1 da figura 2.8) foi configurada de forma dinâmica a partir de um parâmetro da Fonte de dados nomeado como "identificadorPost", esse parâmetro será exibido na lista de parâmetros da aba Filtro (destaque 1 da figura 2.9). Sendo assim, em todas as requisições GET feita para essa Fonte de dados será possível alimentar a querystring "idenficadorPost" que, por sua vez, alimentará a querystring "postId" da requisição montada pela Fonte de dados (destaque 2 da figura 2.9).

Figura 2.9 - Parâmetro de querystring definido nas configurações da Ação Para Obter

O endpoint abaixo é um exemplo de requisição feita para a Fonte de dados da figura 2.9 (query881058), passando o valor "101" para a querystring "identificadorPost" da Fonte de dados (destaque 1 da figura 2.9). Em seguida, a Fonte de dados realiza uma requisição à API configurada (4 da figura 2.9), incluindo as quesrystrings "id" (estática, definida no destaque 2 da figura 2.8) e "postId" (obtida a partir do parâmetro "identificadorPost", destaques 1 das figuras 2.8 e 2.9). Esse fluxo é representado pelos itens 1 e 2 da figura 1.

https://app-8-128-13357.ide.cronapp.io/api/cronapi/odata/v2/app/query881058?identificadorPost=101

Parâmetros do Sistema

O Cronapp também permite que o endereço de uma API possa ser montado a partir de um parâmetro do sistema. Isso pode ser útil em situações onde a API referenciada muda de domínio, gerando um endpoint diferente para os ambientes (perfis) de desenvolvimento ou produção, por exemplo.

Para configurar, basta criar um parâmetro na janela de Parâmetros do Sistema, passando como Valor, o domínio, a rota ou a parte do endpoint que deseja substituir e definir o Perfil (Figura 2.10).

Figura 2.10 - Janela de configurações dos Parâmetros do sistema

Na janela de configurações da Fonte de dados podemos substituir parte do endpoint pelo parâmetro criado, utilizando os caracteres ${} em volta, exemplo: ${domainAPI} (destaque 1 da figura 2.11). Ao executar, a Fonte de dados identificará o perfil e montará o endpoint com base no parâmetro configurado (2). 

Figura 2.11 - Utilizando o parâmetro do sistema para alterar o endpoint da requisição

Aba Ações

Essa aba permite configurar as rotas de comunicações entre a Fonte de dados e a API externa através dos verbos HTTP (Get, Post, Put, Delete), filtrar ou contar; definir a segurança e configurar os parâmetros de querystring usados por cada ação. Nesse momento é importante conhecer como funciona o serviço REST que será utilizado ou acessar sua documentação, pois a API pode utilizar uma mesma URL Base para todas as requisições, possuir um endpoint igual ou diferente para cada verbo HTTP. Além disso, será necessário configurar os parâmetros utilizados para filtrar, ordenar e paginar.

Por padrão, a Fonte de dados sempre inclui automaticamente o valor do identificador do registro no final do endereço da requisição para as ações Para Atualizar e Para Remover, ficando "<Endpoint>/{id}".

Como cada ação pode ter parâmetros e endpoint diferentes, toda requisição feita a uma Fonte de dados Web services em modo debug imprimirá no Console do depurador os parâmetros de querystring gerados e a URL com a requisição completa (Console do depurador, figura 3.1). 

Figura 3.1 - Configuração e execução da ação Para Remover de uma Fonte de dados web services

1. Campo com o Endereço principal: esse endereço pode ser completo (endpoint do verbo Get) ou parcial (URL base), nesse caso, a Fonte de dado irá concatenar a URL base com a Rota definida no campo URL de cada Ação (destaque 8 da figura 3.1). Veja mais detalhes no item 8 dessa lista.
2. "...": abre a janela "Obter campos do serviço" para personalizar os parâmetros da requisição de cada ação.
3. Campo Parâmetro: nome do novo parâmetro de querystring a ser passado na requisição.
4. (+): inclui o novo parâmetro na lista de querystrings.
5. Coluna Nome: lista de parâmetros.
6. Coluna Valor do campo: define como será o valor a ser passado, podendo ser tipos estáticos (texto, numérico, data e hora, hora ou lógico), Bloco de programação, Parâmetro ou Expressões. Acesse o tópico "Parâmetros e constantes" da documentação Fonte de Dados para mais detalhes.
7. Coluna Remover: remove o parâmetro querystring selecionado.
8. Parâmetros fixos:
   • URL: substitui ou modifica o endpoint da requisição para a ação selecionada (verbo HTTP). Esse campo pode estar vazio, com um endereço relativo ou absoluto:
     • Campo URL vazio: se o campo URL estiver vazio, a requisição será feita a partir do endereço principal (destaque 1 da figura 3.1).
       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Obter (8): <vazio>
         Requisição Para Obter (11): https://www.ws.com.br/user
       • Exemplo 2:
         URL Base (1): https://www.ws.com.br/user
         Campo URL da ação Para Atualizar (8): <vazio>
         Requisição Para Atualizar (11): https://www.ws.com.br/user/{id} 



     • Campo URL com valor relativo: algumas APIs possuem uma estrutura de endereço igual (URL base) e altera apenas a rota final. Assim, é possível utilizar a mesma estrutura do campo Endereço principal (destaque 1 da figura 3.1) "<URL BASE>/" e alterar apenas o campo URL (destaque 8 da figura 3.1) para cada verbo HTTP (Ação), com a rota específica da ação (Ex.:  " /list/"), gerando o endpoint completo ao final "<URL Base>/list/". 
       
       

       A concatenação entre o endereço principal (destaque 1 da figura 3.1) e campo URL (destaque 8 da figura 3.1) será diferente se o valor do campo URL iniciar ou não com o caractere barra "/":

       • Se o valor do campo URL começar com o caractere "/", o endpoint será montado com a concatenação do domínio da URL principal (ignorando qualquer rota existente) com o conteúdo do campo URL.
         • Campo Endereço principal (1): https://www.ws.com.br/user/
           Campo URL (8): /insert/
           Requisição (11): https://www.ws.com.br/insert/{id}
       • Se o valor do campo URL não começar com o caractere "/", o endpoint será formado pela simples concatenação do Endereço principal com o conteúdo do campo URL.
         
         • Campo Endereço principal (1): https://www.ws.com.br/user/
           Campo URL (8): insert/
           Requisição (11): https://www.ws.com.br/user/insert/{id}

       
       

       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user/
         Campo URL da ação Para Obter (8): list/
         Requisição Para Obter (11): https://www.ws.com.br/user/list/
       • Exemplo 2:
         URL Base (1): https://www.ws.com.br/user/
         Campo URL da ação Para Remover (8): /remove/
         Requisição Para Remover (11): https://www.ws.com.br/remove/{id}

       
       

     • Campo URL com valor absoluto: é possível informar um endpoint completo no campo URL e ignorar totalmente o endpoint no campo Endereço principal (destaque 1 da figura 3.1).
       • Exemplo:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Obter (8): https://www.ws-2.io/list
         Requisição Para Obter (11): https://www.ws-2.io/list
       • Exemplo 2:
         Campo Endereço principal (1): https://www.ws.com.br/user
         Campo URL da ação Para Remover (8): https://www.ws-2.io/list/{id}
         Requisição Para Remover (11): https://www.ws-2.io/list/123
         
         
   • Caminho: o campo espera receber um JSON Path e é usado para informar qual parte do JSON recebido possui a lista de objetos (ex.: $.data - tudo que estiver dentro do atributo data no objeto JSON). Caso não seja preenchido, será obtido todo o conteúdo da resposta da requisição. 
     
9. Parâmetros: devem ser adicionados e configurados os parâmetros querystring que serão enviados juntos com o endpoint. 
10. Parâmetro compartilhado: nos casos em que várias ações utilizam o mesmo parâmetro, é possível selecionar a opção "Parâmetro" na coluna Valor do campo (6) e informar um nome ao lado (10.a). Esse parâmetro passará a ser configurável a partir da aba Filtro da Fonte de dados (destaque 1 da figura 2.9) e todas as outras ações poderão receber o mesmo valor após selecionar a opção "Parâmetro" e informar o mesmo nome.
11. Endereço requisitado à API: endereço da requisição montado com o que foi definido no campo URL Base (1), URL (8) e nos parâmetros passados (9 e 10), 

Nos subtópicos abaixo listamos as principais ações utilizadas e apresentamos exemplos de como configurá-las. Veja o que representa cada elemento da lista numerada nos exemplos:

1. Endereço principal: endereço usado para configurar a Fonte de dados (destaque 1 da figura 3.1).
2. Campo URL: usado para personalizar o endpoint de cada Ação em sua respectiva janela (destaque 8 da figura 3.1).
3. Caminho: endereço JSON (JSON Path) até a lista de objetos no retorno da requisição (destaque 8 da figura 3.1). 
4. Método: método HTTP utilizado: GET, PUT, POST, DELETE.
5. Requisição final: endereço da requisição montado a partir da configuração dos campos Endereço principal (destaque 1 da figura 3.1), campo URL (destaque 8 da figura 3.1) e parâmetros de querystring (destaques 9 e 10 da figura 3.1).
6. Corpo da requisição enviado para a API: corpo da requisição enviado pela Fonte de dados para a API, utilizado apenas nas ações Para inserir e Para Atualizar.
   Em um formulário Cronapp, o corpo do objeto da requisição é montado e enviado automaticamente pela Fonte de dados, que obtém esses dados dos campos (inputs) do formulário que estão com a propriedade Valor (ng-model) vinculada com a Fonte de dados (ex: <FonteDados>.active.nome).

7. Corpo da requisição retornada pela API: estrutura JSON retornado pela API.

8. Conteúdo do caminho na requisição de retorno: após obter a resposta da API, a Fonte de dados utiliza o caminho (JSON Path) informado (destaque 8 da figura 3.1) para acessar a lista de objetos.
   Durante a configuração da Fonte de dados web services, o caminho é informado no passo 2, a partir do campo Para Obter.

Para Obter (Get)

Essa ação é responsável por obter os dados do recurso e, dependendo da chamada, pode retornar um único elemento ou uma lista de elementos.

Exemplo 1 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço Principal: https://meusistema.com.br/api/users
2. Campo URL: <vazio>
3. Caminho: $.data
4. Método: GET
5. Requisição final: https://meusistema.com.br/api/users
6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   {
       "page": 1,
       "per_page": 6,
       "total": 12,
       "total_pages": 2,
       "data": [
           {
               "id": 1,
               "email": "js@cronapp.io",
               "nome": "João Souza"
           },
           {
               "id": 2,
               "email": "ma@cronapp.io",
               "nome": "Maria Andrade"
           },
           ...
       ],
       "support": {
           "url": "https://www.cronapp.io",
           "text": "this is an example"
       }
   }

8. Conteúdo do caminho na requisição de retorno:

   [
       {
           "id": 1,
           "email": "js@cronapp.io",
           "nome": "João Souza"
       },
       {
           "id": 2,
           "email": "ma@cronapp.io",
           "nome": "Maria Andrade"
       },
       ...
   ]

Exemplo 2 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço Principal: https://meusistema.com.br/api/user
2. Campo URL: expression: ${primaryKey}
3. Caminho: <vazio>
4. Método: GET
5. Requisição final: https://meusistema.com.br/api/user/2
6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   {
       "id": 2,
       "email": "ma@cronapp.io",
       "nome": "Maria Andrade"
   }

8. Conteúdo do caminho na requisição de retorno:
   

   {
       "id": 2,
       "email": "ma@cronapp.io",
       "nome": "Maria Andrade"
   }

Exemplo 3 (Get)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/v2/api/list
2. Campo URL: /api/users
3. Caminho: $.data
4. Método: GET
5. Requisição: https://meusistema.com.br/api/users?page=1&per_page=6
   • page: top
   • per_page: per_page 
6. Corpo da requisição enviado para a API: <vazio>

7. Corpo da requisição retornada pela API:

   {
       "page": 1,
       "per_page": 6,
       "total": 12,
       "total_pages": 2,
       "data": [
           {
               "id": 1,
               "email": "js@cronapp.io",
               "nome": "João Souza"
           },
           {
               "id": 2,
               "email": "ma@cronapp.io",
               "nome": "Maria Andrade"
           },
           ...
       ],
       "support": {
           "url": "https://www.cronapp.io",
           "text": "this is an example"
       }
   }

8. Conteúdo do caminho na requisição de retorno:

   [
       {
           "id": 1,
           "email": "js@cronapp.io",
           "nome": "João Souza"
       },
       {
           "id": 2,
           "email": "ma@cronapp.io",
           "nome": "Maria Andrade"
       },
       ...
   ]

Para Inserir (Post)

Ação utilizada para incluir novos elementos ao serviço. O conteúdo a ser adicionado é enviado no corpo da requisição e alguns serviços retornam o próprio elemento, sinalizando sucesso na operação.

Exemplo 1 (Post)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL: <vazio>
3. Caminho: <vazio>
4. Método: POST
5. Requisição final: https://meusistema.com.br/api/user

6. Corpo da requisição enviada para a Fonte de dados: 
   

   {
       "id": 3,
       "email": "pp@cronapp.io",
       "nome": "Pedro Porto"
   }

   
   

7. Corpo da requisição retornada pela API:

   {
       "id": 3,
       "email": "pp@cronapp.io",
       "nome": "Pedro Porto"
   }

8. Conteúdo do caminho na requisição de retorno:

   {
       "id": 3,
       "email": "pp@cronapp.io",
       "nome": "Pedro Porto"
   }

Exemplo 2 (Post)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL: insert
3. Caminho: $.inserted
4. Método: POST
5. Requisição final: https://meusistema.com.br/api/user/insert

6. Corpo da requisição enviada para a Fonte de dados:
   

   {
       "id": 3,
       "email": "pp@cronapp.io",
       "nome": "Pedro Porto"
   }

   
   

7. Corpo da requisição retornada pela API:

   {
       "inserted": {
           "id": 3,
           "email": "pp@cronapp.io",
           "nome": "Pedro Porto"
       }
   }

8. Conteúdo do caminho na requisição de retorno:

   {
       "id": 3,
       "email": "pp@cronapp.io",
       "nome": "Pedro Porto"
   }

Para Atualizar (Put)

Ação utilizada para modificar algum registro. O conteúdo a ser atualizado é enviado no corpo da requisição e alguns serviços retornam o próprio elemento, sinalizando sucesso na operação.

Exemplo 1 (Put)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL <vazio>
3. Caminho: <vazio>
4. Método: PUT
5. Requisição final: https://meusistema.com.br/api/user/<Primary_key>

6. Corpo da requisição enviado para a API:
   

   {
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"
   }

   
   

7. Corpo da requisição retornada pela API:

   {
       "id": 3,
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu" 
   }

8. Conteúdo do caminho na requisição de retorno:

   {
       "id": 3,
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"  
   }

Exemplo 2 (Put)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL: expression: update/${primaryKey}
3. Caminho: $.updated
4. Método: PUT
5. Requisição final: https://meusistema.com.br/api/user/update/<Primary_key>

6. Corpo da requisição enviado para a API:
   

   {
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"
   }

   
   

7. Corpo da requisição retornada pela API:

   {
       "updated": {
           "id": 3,
     		"email": "hd@cronapp.io",
       	"nome": "Haila Dimitrescu" 
       }
   }

8. Conteúdo do caminho na requisição de retorno:

   {
       "id": 3,
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"  
   }

Para Remover (Delete)

Operação utilizada para excluir algum recurso do serviço. Alguns serviços retornam o próprio elemento, sinalizando sucesso na operação.

Exemplo 1 (Delete)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL: <vazio>
3. Caminho: <vazio>
4. Método: DELETE
5. Requisição final: https://meusistema.com.br/api/user/<Primary_key>

6. Corpo da requisição enviado para a API: <desconsiderado>

7. Corpo da requisição retornada pela API:

   {
       "id": 3,
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"  
   }

8. Conteúdo do caminho na requisição de retorno: <desconsiderado>

Exemplo 2 (Delete)

1. Endereço principal: https://meusistema.com.br/api/user 
2. Campo URL: expression: delete/${primaryKey}
3. Caminho: <vazio>
4. Método: DELETE
5. Requisição final: https://meusistema.com.br/api/user/delete/<Primary_key>  

6. Corpo da requisição enviado para a API: <desconsiderado>

7. Corpo da requisição retornada pela API:

   {
       "id": 3,
       "email": "hd@cronapp.io",
       "nome": "Haila Dimitrescu"  
   }

8. Conteúdo do caminho na requisição de retorno: <desconsiderado>

Exemplo 3 (Delete)

Acesse a descrição dos campos abaixo para mais detalhes.

1. Endereço principal: https://meusistema.com.br/api/user
2. Campo URL: <vazio>
3. Caminho: <vazio>
4. Método: DELETE
5. Requisição final: https://meusistema.com.br/api/user/delete?id=<Primary_key>

6. Corpo da requisição enviado para a API: <desconsiderado>

7. Corpo da requisição retornada pela API: <vazio>

8. Conteúdo do caminho na requisição de retorno: <desconsiderado>

Para Filtrar (Filter)

A ação Para Filtrar é utilizada em conjunto com a ação Para Obter, deve possuir os mesmos parâmetros utilizados em Para Obter e mais os parâmetros de filtros usados pelo recurso.

Na figura abaixo acrescentamos o parâmetro de filtro (search) usado pelo recurso e alimentamos com a constante da Fonte de dados simpleFilter. A Fonte de dados possui uma série de constantes que facilitam essa conversão, acesse o tópico "Parâmetros e Constantes" da Fonte de dados para mais detalhes.

Figura 3.2 - Configuração da ação Para Filtrar

Para Contar (Count)

A ação Para Contar é utilizada em conjunto com a ação Para Obter e não necessita de parâmetros próprios, mas o campo Caminho deve apontar, usando o JSON Path, para o atributo que informa a quantidade total de elementos. Esse campo normalmente é preenchido de forma automática pelo Cronapp quando executamos os passos que obtém os campos da requisição. Se o serviço REST não retornar um valor para o total de registros, o Cronapp considerará a quantidade de registros retornados, sendo que isso pode prejudicar a paginação.

Figura 3.3 - Configuração da ação Para Contar

Aba Campos

A aba Campos deve conter os atributos do objeto obtido pelo serviço REST. Após executar os passos iniciais de configuração do Web Service (destaque 1 da figura 4.1), o Cronapp tenta obter e configurar automaticamente todos os campos do objeto, deixando os campos com os mesmos nomes dos atributos do objeto. É possível adicionar um novo campo (2) e, em seguida, configurar na janela Caminho (3) o nome do atributo do objeto que vai alimentar esse campo. O campo da janela Caminho espera receber um JSON Path a partir do objeto principal.

Figura 4.1 - Configuração da aba Campos

Aba Cabeçalhos

Permite configurar os cabeçalhos das requisições HTTP. Por padrão, os campos Accept e Content-Type já vêm definidos em Fontes de dados do tipo Web Services. Porém, é possível alterá-los ou adicionar novos cabeçalhos usados pela API.

Cabeçalhos são utilizados, por exemplo, em serviços REST privados que necessitam de algum tipo de autenticação. Normalmente essa autenticação é enviada via cabeçalho e os mais comuns são authorization e x-auth-token. Para alimentar esses campos, podemos usar as constantes de token ou selecionar um bloco de programação que retorna esse valor (destaque 1). 

Figura 5.1 - Configuração da aba Cabeçalhos

Autenticação entre projetos Cronapp

Se você possui ao menos 2 projetos Cronapp (exemplo: Projeto Servidor e Projeto Cliente) em que um irá servir recursos REST para os outros, é possível configurar para que ambos projetos possuam o mesmo valor no campo Token da janela de Configurações do projeto (aba Configurações do projeto) (destaque 1 da figura 5.2). Dessa forma, o Projeto Servidor ficará responsável pela autenticação e autorização do Projeto Cliente, retirando a responsabilidade do Projeto Cliente de gerar requisições o manter o Token de autenticação dos usuários sempre atualizado.

Figura 5.2 - Configuração do mesmo Token em ambos projetos

Após isso, basta selecionar a constante token (Figura 5.3) no campo do cabeçalho x-auth-token dos projetos clientes. Acesse o tópico "Parâmetros e Constantes" da documentação Fonte de Dados para mais detalhes sobre as constantes Cronapp.

Figura 5.3 - Autenticando as requisições a partir da constante token

Web Service - SOAP

Antes de criarmos uma Fonte de dados SOAP, precisamos ter em mãos o endereço do arquivo *.wsdl do serviço que iremos usar e, em seguida, realizar os passos abaixo.

Passos para obter campos do serviço

Durante os passos a seguir, o Cronapp tentará obter os campos do objeto a partir do método selecionado. As configurações apresentadas aqui podem ser alteradas após o processo.

Para criar a Fonte de dados, acesse o Botão do menu do sistema > Fonte de dados (destaque 1 da figura 6) e, após abrir a janela, clique no botão Nova Fonte de dados (destaque 2). 

Figura 6 - Criando uma Fonte de dados

Com a janela da Fonte de dados aberta, preencha os campos Identificador e Nome da consulta, em seguida, selecione a opção Web Services (destaque 1 da figura 6.1) e informe o endereço do *.wsdl SOAP no campo ao lado (destaque 2). Por fim, clique no botão Obter campos do serviço (destaque 3) para abrir a janela de configuração.

Figura 6.1 - Informando endereço do arquivo WSDL e iniciando a configuração

A primeira janela exibe o campo URL com o endereço do *.wsdl que informamos no passo anterior e mais os campos dos cabeçalhos Accept e Content-Type usados na requisição. Esse e outros cabeçalhos podem ser configurados posteriormente na aba Cabeçalhos.

Figura 6.2 - Configuração da URL e Cabeçalhos

1. URL: endereço do arquivo*.wsdl que informamos no passo anterior (destaque 2 da figura 6.1).
2. Novo Cabeçalho: se o recurso necessita de cabeçalhos próprios, como os de autenticação (exemplos: authorization ou x-auth-token), é possível informar o nome do cabeçalho e adicionar à lista clicando no ícone (+).
3. Lista de cabeçalhos: essa lista aceita apenas valores estáticos, após obter os campos, utilize a aba Cabeçalhos para configurar os cabeçalhos com valores dinâmicos, 

Clique em Avançar.

Na próxima tela (Figura 6.3), o campo Resultado exibirá uma estrutura JSON com todos os métodos e seus parâmetros contidos no WSDL. 

Figura 6.3 - Localizando os dados no JSON

• Para Obter: esse campo exibe a lista com todos os métodos, selecione o método GET desejado.
• Para Contar: esse campo é utilizado para a paginação e exibe a lista com todos os métodos do arquivo WSDL. Apesar de ser incomum a paginação em serviços SOAP, se o serviço possuir uma função que retorne a quantidade de elementos do método GET, selecione aqui. Caso contrário, deixe-o em vazio.
• Resultado: lista dos métodos e seus parâmetros.

Esses campos podem ser editados posteriormente na aba Ações.

Clique em Avançar.

Após identificar o retorno do método selecionado no passo anterior, o Cronapp identificará e exibirá um objeto com todos os seus campos em Resultado (Figura 6.4). 

Figura 6.4 - Configuração dos identificadores do objeto

• Resultado: primeiro objeto da lista.
• Contagem: exibe o total de registros retornado, caso não selecione nenhum método no campo Para Contar do passo anterior, esse campo ficará vazio.
• Chaves: o Cronapp tentará identificar qual a chave do objeto, caso não consiga identificar, todos os campos serão marcados com chaves. Clique no campo para selecionar o campo chave ou apenas avance. Essa configuração poderá ser feita depois na aba Campos.

Clique em Avançar para finalizar e retornar a Fonte de dados.

Aba Ações

A aba Ações permite selecionar um método do serviço para cada um dos verbos HTTP (get, post, put, delete), filtrar ou contar; definir a segurança e configurar os atributos usados por cada ação. Nesse momento é importante conhecer como funciona o serviço que será utilizado ou acessar sua documentação.

Figura 7 - Configuração da aba Ações

Na coluna Nome (destaque 1 da figura 7) são exibidos os parâmetros utilizados pelo método selecionado, já na coluna Valor do campo (2) define como o valor será passado, podendo ser tipos estáticos (texto, numérico, data e hora, hora ou lógico), Bloco de programação, Parâmetro ou Expressões. Acesse o tópico "Parâmetros e constantes" da documentação Fonte de Dados para mais detalhes.

No exemplo da figura 7, estamos usando um bloco de programação para obter o valor do CEP.

As ações devem ser configuradas com base na API utilizada, por isso é necessário acessar a sua documentação e verificar se a API possui suporte a todos os recursos de CRUD e também paginação, ordenação e filtro.

• Para Obter: essa ação é responsável por chamar o método que irá obter os dados do recurso. A Fonte de dados aceita que o método retorne um valor primitivo ou composto, veja mais detalhes no próximo tópico (Aba Campos).
• Para Inserir: ação que chamará o método que incluirá novos dados ao serviço.
• Para Atualizar: ação utilizada para modificar algum registro.
• Para Remover: operação utilizada para excluir algum recurso do serviço.
• Para Filtrar: utilizada em conjunto com a ação Para Obter, o método selecionado deve gerar filtros nos dados retornados.
• Para Contar: não é muito comum utilizar paginação em SOAP, porém, caso o serviço possua um método que retorne o total de registros obtidos pelo método em Para Obter, selecione-o aqui.

A ação Para Filtrar é utilizada em conjunto com a ação Para Obter, deve possuir os mesmos parâmetros utilizados em Para Obter e mais os parâmetros de filtros usados pelo recurso.

Aba Campos

A aba Campos deve conter os atributos do objeto obtido pelo serviço SOAP. Após executar os passos iniciais de configuração do Web Service (destaque 1 da figura 8), o Cronapp tenta obter e configurar automaticamente todos os campos na aba Campos, deixando o campo com o mesmo nome do atributo do objeto. É possível adicionar um novo campo (2) e, em seguida, configurar na janela Caminho (3) o nome do atributo do objeto que vai alimentar esse campo. O campo da janela Caminho espera receber o nome do atributo do objeto principal do XML.

Figura 8 - Configuração da aba Campos

O método selecionado na ação Para Obter (aba Ações) pode retornar tipos complexos (objetos) ou simples (valor texto, numérico, booleano...). Quando o retorno for um objeto, cada atributo representará um campo, já quando for um tipo simples, o conteúdo será convertido em um objeto cujo único atributo será o "content" e será representado pelo campo de mesmo nome.

{
    "content": "texto de retorno do método"
}

Aba Cabeçalhos

Permite configurar os cabeçalhos das requisições HTTP. Por padrão, os campos Accept e Content-Type já vêm definidos em Fontes de dados do tipo Web Services, porém é possível alterá-los e adicionar novos cabeçalhos usados pelo recurso web.

Cabeçalhos são utilizados, por exemplo, em serviços privados que necessitam de algum tipo de autenticação e normalmente são enviados via cabeçalho. Para alimentar esses campos, podemos usar as constantes de token ou selecionar um bloco de programação que retorna esse dado (destaque 1 da figura 9). Para mais detalhes, acesse o tópico "Aba Cabeçalhos" da Fonte de dados.

Figura 9 - Configuração da aba Cabeçalhos