Existem 2 contextos definidos que se aplicam tanto para a Antiga arquitetura (Jboss) quanto para o DTS4THF (Tomcat).

Estes contextos tem o objetivo de definir o acesso das requisições, ou seja, se são contextos de acessos internos (via menu) pelo contexto DTS/DATASUL-REST ou acessos externos (via APPs por exemplo) pelo contexto /API.

O Guia de Implementação de API TOTVS define que no formato das URIs dos endpoints deve conter:

• o nome do produto;
• o módulo;
• a versão da API;
• o recurso alvo da funcionalidade em questão.

Modelo de acesso aos Contextos:

Para "publicar" a funcionalidade Progress ABL basta criar o programa (.p) com o seguinte caminho: sec/api/v1/users.p (<módulo>/api/<versão API>/<recurso>.p). 

A sub-pasta "api" passa então a concentrar todas as funcionalidades de integração do módulo em questão:

     O Guia de Implementação de API TOTVS define também que a troca de mensagens é feita (impreterivelmente) no formato JSON, e por conta disso, a troca de mensagens com as funcionalidades Progress também devem ser feitas nesse formato, mais especificamente por meio de um parâmetro de entrada e outro de saída do tipo LONGCHAR que devem ser devidamente tratados (parseados e formatados) pela funcionalidade utilizando as includes utilitárias disponibilizadas:

• utp/ut-api.i: Faz o parser do parâmetro LONGCHAR de entrada e cria um objeto JsonObject chamado jsonInput.
• utp/ut-api-action.i: Faz o roteamento do objecto jsonInput para uma procedure interna especificada pelo desenvolvedor.
• utp/ut-api-notfound.i: Caso nenhuma procedure interna tenha sido encontrada, retorna uma mensagem "Method not found" com HTTP Status 400.
  
  

>>>>>Abaixo um exemplo de recurso desenvolvido em Progress ABL para ser utilizado junto ao serviço de API<<<<<<

{utp/ut-api.i}
{utp/ut-api-action.i pi-send    GET /~*/SEND by=email,address=~* }
{utp/ut-api-action.i pi-update  POST /~* }
{utp/ut-api-action.i pi-find    GET /~* }
{utp/ut-api-action.i pi-default GET }
{utp/ut-api-notfound.i}
  
PROCEDURE pi-send:
    DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
     
    DEFINE VARIABLE aJsonArray  AS JsonArray  NO-UNDO.
    DEFINE VARIABLE oJsonObject AS JsonObject NO-UNDO.
 
    aJsonArray = NEW JSONArray().
 
    oJsonObject = NEW JSONObject().
    oJsonObject:ADD("teste", "teste").
    oJsonObject:ADD("teste1", "teste1").
    oJsonObject:ADD("teste2", "teste2").
    aJsonArray:ADD(oJsonObject).
 
    oJsonObject = NEW JSONObject().
    oJsonObject:ADD("teste", "teste").
    oJsonObject:ADD("teste1", "teste1").
    oJsonObject:ADD("teste2", "teste2").
    aJsonArray:ADD(oJsonObject).
 
    jsonOutput = JsonAPIResponseBuilder:ok(aJsonArray, false).
END.
  
PROCEDURE pi-update:
    DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.

    jsonOutput = NEW JSONObject().
    jsonOutput = jsonInput.
END.
 
PROCEDURE pi-find:
    DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    jsonOutput = NEW JSONObject().
    jsonOutput:ADD("method", "GET").
    jsonOutput:ADD("procedure", "pi-find").
    jsonOutput:ADD("description", "Test").
END.

PROCEDURE pi-default:
    DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    jsonOutput = NEW JSONObject().
    jsonOutput:ADD("method", "GET").
    jsonOutput:ADD("procedure", "pi-default").
    jsonOutput:ADD("description", "Test").
END.

     No exemplo acima, temos as seguintes includes utilitárias:

Com o objetivo de facilitar a manipulação dos objetos JsonObject recebidos e enviados pela API Progress foram desenvolvidas algumas classes de utilitários:

• JsonAPIRequestParser - Extrai informações do objeto JSON recebido como parâmetro da requisição.
• JsonAPIResponse - Trata a criação do objeto JSON de response da requisição.
• JsonAPIResponseBuilder - Trata a criação do objeto JSON de response da requisição através de um builder.
• JsonAPIUtils - Utilitário com métodos que facilitam a manipulação de informações relacionados a API

O objeto JsonObject, recebido pela requisição no programa Progress conterá informações completas da requisição, desde informações do:

• HEADER;
• QUERY PARAMs;
• PATH PARAMs;
• o próprio PAYLOAD e;
• arquivos MULTIPART.

Com esta mensagem, o desenvolvedor poderá efetuar os devidos filtros e classes utilitárias necessárias. 

Exemplo de mensagem:

{ 
    uri: valor,
	method: GET,
    headers: {},
	pathParams: [ "param1", "param2" ],
	queryParams: { query1: [valor1, valor2], query2: [valor1]},
	payload: { },
	multyPartFile: [ {file: ...}, {file: ...}]
}

O cliente pode fazer acesso a diferentes empresas via BASIC AUTHENTICATION. Para realizar esse processo é necessário primeiramente o login no sistema, e em seguida descobrir todas as empresas do produto, selecionando um dos links a seguir: 

• (JBoss ou Tomcat): http://<host>:<port>/api/btb/v1/companies
• (JBoss): http://<host>:<port>/dts/datasul-rest/resources/btb/v1/companies
• (Tomcat): http://<host>:<port>/dts/datasul-rest/resources/prg/btb/v1/companies

A partir do momento que se sabe qual empresa se deseja enviar na requisição e que a mesma está associada ao usuário, é possível fazer a chamada da API que desejar, passando o código como parâmetro dentro do atributo companyId, esse especificado dentro do Header.

GET /api/btb/v1/companies HTTP/1.1
Host: host:port
companyId: 10
Authorization: Basic MTM6MTM=

Para a arquitetura do JBOSS é possível realizar o logout via as chamadas REST. Isso pode ser feito para que os contextos de trabalho com o josso sejam liberados e que a session seja invalidada no fechamento dos APPs.

Desta maneira, existe a seguinte url para realizar o logout no produto via chamada REST.

Contexto api
http://host:port/api/logout

Contexto dts/datasul-rest
http://host:port/dts/datasul-rest/resources/logout