Serviço Progress
Expandir |
---|
title | Clique para visualizar o conteúdo |
---|
|
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: Aviso |
---|
Os programas Progress disponibilizados, deverão seguir o padrão de localização abaixo e devem estar compilados, ou seja, é necessário o *.r: <módulo>/api/<versão API>/<recurso>.r |
---|
OBS: Outros caminhos e parâmetros podem ser adicionados a URL, mas sempre de acordo com o Guia de Implementação de APIs. |
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<<<<<< Expandir |
---|
title | Clique para visualizar o exemplo ... |
---|
| No início do código estão todas as includes necessárias. O que vale ressaltar neste trecho é referente a include ut-api-action: - Nesta include são declaradas as procedures utilizadas na API, por exemplo: pi-send, pi-update.
- Na mesma declaração é definido qual o método http aplicado, por exemplo: GET, POST, entre outros.
- Em seguida é definido como o recurso será acessado pela URI, por exemplo: /~*/SEND
- Isso significa que ao acessar a URI teremos algo como: http://host:port/dts/datasul-rest/resources/prg/sec/v1/users/send onde:
draw.io Diagram |
---|
border | true |
---|
viewerToolbar | true |
---|
fitWindow | false |
---|
diagramName | estrutura |
---|
simpleViewer | false |
---|
width | 600 |
---|
links | auto |
---|
tbstyle | top |
---|
lbox | true |
---|
diagramWidth | 785 |
---|
revision | 5 |
---|
|
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 |
|
|
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:
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"). AS JsonArray NO-UNDO.
DEFINE VARIABLE oJsonObject AS JsonObject NO-UNDO.
|
| jsonOutput:ADD("procedure", "pi-find"aJsonArray = NEW JSONArray().
|
| jsonOutput oJsonObject = NEW JSONObject().
oJsonObject:ADD(" |
| descriptionTest.
END
PROCEDURE pi-default:DEF INPUT PARAM jsonInput AS JsonObject NO-UNDOoJsonObject:ADD("teste1", "teste1").
|
| DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
oJsonObject:ADD("teste2", "teste2").
aJsonArray:ADD(oJsonObject).
|
| jsonOutputoJsonObject = NEW JSONObject().
|
| jsonOutputmethodGETjsonOutputprocedurepi-defaultjsonOutputdescriptionTestEND. |
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.
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. |
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. Através desta mensagem, o desenvolvedor poderá efetuar os devidos filtros e classes utilitárias necessárias.
Exemplo de mensagem:
Bloco de código |
---|
|
{
uri: valor,
method: GET,
headers: {},
pathParams: [ "param1", "param2" ],
queryParams: { query1: [valor1, valor2], query2: [valor1]},
payload: { },
multyPartFile: [ {file: ...}, {file: ...}]
} |
Classes utilitárias
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: draw.io Diagram |
---|
border | true |
---|
viewerToolbar | true |
---|
fitWindow | false |
---|
diagramName | utilitarios |
---|
simpleViewer | false |
---|
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. |
|