NOME DO REQUISITO

1. Pré-requisitos
   
   1. Plataforma com suporte REST e autenticação Basic.
   2. Suporte a tratamento cross-domain, por conta das requisições de serviços em servidores de domínio diferente.
   3. O modelo de implementação dessa API foi criado seguindo o documento "Guia de implementação de API" disponível no link abaixo:
      http://tdn.totvs.com/pages/viewpage.action?pageId=274849083
      
      
2. Definições gerais

   1. Os retornos dos serviços REST devem estar encapsulados dentro de um objeto JSON com a seguinte especificação:
      Mensagens de erro

      Para todas as mensagens que representam um erro (códigos HTTP 4xx e 5xx) deve-se retornar obrigatoriamente os campos a seguir:

      {     code: "",     message: "",     detailedMessage: "" } Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {     code: "",     message: "Erro ao testar conexão com o banco de dados",     detailedMessage: "Banco de dados oracle não disponível" }

      
      Mensagens de sucesso

      Mensagens de sucesso (código http 2xx devem) devem retornar diretamente a entidade que representa o objeto resultado da operação do endpoint. Ex:
      

      Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {   testConnection: "true" }

      
      
      

   2. Todas as linhas de produto devem estabelecer uma URL base, a partir da qual os serviços REST de provedor integrado serão disponibilizados. 

   3. Como exemplo, no ERP RM foi definida a seguinte  URL base: 
      /api/trep/v1/dbdataproviders/ 
      
      

      Informações
      Com o intuito de facilitar o entendimento do documento, a URL base do RM descrita acima será utilizada no restante do documento.

      
      

3. Descrição dos serviços
   

   Os serviços REST descritos a seguir estão divididos em:

   • Serviço de leitura de parâmetros gerais;
   • Serviço de teste de conexão;
   • Serviço de teste de sentenças sql;
   • Serviço de leitura de schema de tabelas físicas;
   • Serviço de leitura de schema de sentença sql;
   • Serviço de retorno de dados;

   Na descrição de cada serviço podemos encontrar os seguintes elementos:

   • Definição da URL do serviço;
   • Parâmetros de request (entrada) e  response (saída);
   • Descrição do serviço com detalhes relativos ao seu funcionamento;
     
     
     
   1. Serviço de leitura de parâmetros de provedor;
      

      GET /api/trep/v1/dbdataproviders/parameters      

      Recebe	Não recebe parâmetros
      Retorna	Application/JSON

      Esse método é utilizado para obter os parâmetros do provedor integrado do tipo "dados relacionais". A necessidade e definição desses parâmetros é de responsabilidade do dono do provedor. No JSON de retorno, deve constar as seguintes informações:

      • name: Nome do parâmetro;
      • description: Descrição do parâmetro;
      • value: Valor do parâmetro;

      • isPassword: Define se o valor do parâmetro será gravado e mostrado de forma criptografada. Pode ser true ou false
        
        

        Informações
        title Exemplo de json de retorno
        {        “providerParams” : [{              “name” : “aliasName”,              “description” : “Nome do alias do RM”,              “value” : “CorporeRM”,              “isPassword” : false,        }] }

       Os parâmetros retornados por esse serviço aparecerão na grid de parâmetros localizada no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:

      
      

      

      
      

      
      

   2. Serviço de teste de conexão do provedor
      POST /api/trep/v1/dbdataproviders/testconnection

      Recebe	Application/JSON
      Retorna	Application/JSON

      Esse método é utilizado para testar a conexão de um provedor integrado do tipo "dados relacionais". 
      No Json de entrada devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".

      Informações
      title Exemplo de json de entrada
      {        “providerParams” : [{              “name” : “aliasName”,              “description” : “Nome do alias do RM”,              “value” : “CorporeRM”,              “isPassword” : false,        }] }

      
      

       No JSON de retorno, deve constar as seguintes informações:

      • testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
        
        

        Informações
        title Exemplo de json de retorno
        {        “testSuccess” : true; }

      Esse método é utilizado no click do botão "Teste conexão" localizado no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:

      

      
      
      

   • Serviço de teste de sentenças sql
     POST /api/trep/v1/dbdataproviders/testquery

     Recebe	Application/JSON
     Retorna	Application/JSON

     Esse método é utilizado para testar a sintaxe de uma sentença sql. 
     
     

     No Json de entrada devem ser enviadas os seguintes informações: 
     
     

   • providerParams: Parâmetros do provedor de dados. Devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".
   • sqlText: Texto da sentença sql;
   • sqlParameters: Parâmetros da sentença sql;
     • paramName: Nome do parâmetro da sentença sql;
     • paramValue: Valor do parâmetro da sentença sql;
     • paramType: Tipo do parâmetro;

     
     

     Informações
     title Exemplo de json de entrada
     { “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }] }

           No JSON de retorno, deve constar as seguintes informações:

   • testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
     
     

     Informações
     title Exemplo de json de retorno
     {        “testSuccess” : true; }

• • Serviço de leitura de schema de tabelas físicas;
    
    GET /api/trep/v1/dbdataproviders/schematable

    Recebe	Application/JSON
    Retorna	Application/JSON

    Esse método é utilizado para retornar o schema (estrutura) de uma tabela localizada fisicamente em um determinado provedor de dados. 
    
    

    No Json de entrada devem ser enviadas os seguintes informações: 
    
    

    • providerParams: Parâmetros do provedor de dados. Devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".
    • tableSourceName: Nome da tabela do banco de dados;

    • tablesSourceGetRelations: Lista de todas as tabelas físicas cadastradas no dicionário de dados do relatório. Através dessa lista, todas os relacionamentos entre essas tabelas poderão ser recuperados automaticamente. Evitando assim, o cadastro manual dos relacionamentos.
      
      

      Informações
      title Exemplo de json de entrada
      { “providerParams” : [{ “name” : “aliasName”, “description” : “Nome do alias do RM”, “value” : “CorporeRM”, “isPassword” : false, }], "tableSourceName": "PFUNC", "tablesSourceGetRelations": [ {"tableSourceName", "PFUNC"}, {"tableSourceName", "PFUNC"} ] }

  •         No JSON de retorno, deve constar as seguintes informações:

    • testSuccess: Informa se o teste do bem sucedido. Pode ser true ou false
      
      

      Informações
      title Exemplo de json de retorno
      {        “testSuccess” : true; }