Serviço Progress
Para
Expandir |
---|
title | Clique para ver o conteúdo |
---|
|
Para "publicar" a funcionalidade Progress ABL basta criar o programa (.p) com o seguinte caminho: fnd/api/v1/users.p (<módulo>/api/<versão API>/<recurso>.p). |
A A sub-pasta "api" passa então a concentrar todas as funcionalidades de integração do módulo em questão |
. Outros caminhos e parâmetros podem ser adicionados a URL, mas sempre de acordo com o Guia de Implementação de APIs.: Aviso |
---|
Os programas Progress disponibilizados, deverão seguir o padrão de localização abaixo e devem estar compilados, ou seja, é preciso do *.r: <módulo>/api/<versão API>/<recurso>. |
---|
| p
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 |
deve feita 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 |
através das 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: Expandir |
---|
title | Clique para visualizar o exemplo ... |
---|
| Bloco de código |
---|
| {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: |
{utp/ut-api.i}
É a include principal, que possui os parâmetros de entrada e saída do serviço API, nesta include é feito a inicialização das funções utilitárias.
{utp/ut-api-action.i pi-send GET /~*/SEND by=email,address=~* }
Neste exemplo, está sendo definido uma rota, sendo que toda requisição de método GET, que contenha os filtros informados, será direcionado a procedure pi-send.
/~*/SEND by=email,address=~*
Em relação ao filtro informado, será capturado todas as requisições que possuírem um parâmetro Path "SEND", um parâmetro Query "by" com conteúdo "email" e um parâmetro Query "address" com qualquer conteúdo (*).
{utp/ut-api-action.i pi-update POST /~* }
No exemplo acima, está sendo definida uma rota, no qual toda requisição de método POST, será direcionada para a procedure pi-update.
{utp/ut-api-action.i pi-find GET /~* }
Neste exemplo, todas as requisições de método GET, que possuirem parâmetros (Query ou Path) informados, será direcionado para a procedure pi-find.
{utp/ut-api-action.i pi-default GET }
No exemplo acima, para requisições de método GET, que não encontrarem nenhuma rota compatível, será direcionada para a procedure pi-default.
{utp/ut-api-notfound.i}
Caso nenhuma procedure interna tenha sido encontra retorna uma mensagem "Method not found" com HTTP Status 400. draw.io Diagram |
---|
border | true |
---|
viewerToolbar | true |
---|
| |
---|
fitWindow | false |
---|
diagramName | utilitarios |
---|
simpleViewer | false |
---|
width | |
---|
diagramWidth | 1079 |
---|
revision | 5 |
---|
|
Informações |
---|
Algumas considerações sobre o uso da include de roteamento (ut-api-action): - Os roteamentos devem ser definidos do mais específico (detalhado) para o mais genérico (simples);
- O utilitário faz uso da função MATCHES do Progress, que basicamente permite o uso do ponto "." (ponto) como coringa de uma determinada posição (1 caractere apenas) e o "*" (asterisco) para um conjunto de caracteres variáveis;
- O caracter de escape "~" deve ser utilizado sempre que necessário, antecedendo caracteres especiais que comprometam a compilação do código progress;
- Para definir mais de um parâmetro de pesquisa, utilize "," (vírgula) como separador. O processamento de mais de um parâmetro de pesquisa será sempre traduzido para usar o operador AND.
- Permite o uso de todos métodos HTTP suportados pelo API Manager (GET, POST, PUT, DELETE, PATCH, ...)
|
Informações |
---|
A include ut-api.i precisa ser adicionada obrigatoriamente no início do programa Progress, visto que esta include faz uso da instrução USING para importação de classes. Portanto, devido a esta caraterística do Progress ABL, somente será possível adicionar outras includes depois da adição da ut-api.i e ut-api-notfound.i, respectivamente. |
|