Para garantir o controle de erros, controle de chamada EPC e padronização no retorno das mensagens, foram criadas includes para executar os principais Endpoints, além de permitir a chamada de Endpoints específicos de negócio: | Include | Parâmetros da Include | Endpoint | Descrição | Parâmetros enviado para PI Interna |
|---|
utp/ut-api-exec-metadata.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Metadata | Devolve metadata para geração das telas. | - oInput (INPUT): Dados recebidos na requisição;
- cEvent (INPUT): Evento solicitado pelo Front (list, new, edit, copy ou detail);
- cVersion (INPUT): Versão solicitada pelo Front;
- oOutput (OUTPUT): Objeto de Metatadata;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-vld-form.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| VldForm | Validação de formulário. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-vld-field.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| VldField | Validação de campo. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-get.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Get | Busca um registro. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- cExpandables (OUTPUT): Lista de entidades "filhas" separadas por vírgula;
- RowErrors (OUTPUT): Tempable de Erros.
| utp/ut-api-exec-query.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Query | Busca vários registros. | - oInput (INPUT): Dados recebidos na requisição;
- aResult (OUTPUT): Array retornado pelo programa de negócio;
- lHasNext (OUTPUT): Indicação se existem mais registros;
- cExpandables (OUTPUT): Lista de entidades "filhas" separadas por vírgula;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-create.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Create | Criação de registro. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-update.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Update | Alteração de registro. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-patch.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Patch | Alteração de registro. | - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-delete.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| Delete | Eliminação de registro. | - oInput (INPUT): Dados recebidos na requisição;
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-delete-list.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada.
| DeleteList | Eliminação em lote. | - oInput (INPUT): Dados recebidos na requisição;
- aDeletedIdList (OUTPUT): Array da lista de Chaves dos Registros que foram Excluídos, no formato: [{key1:”xx”, keyN:”xx”}, {key1:”xx”, keyN:”xx”}];
- RowErrors (OUTPUT): TempTable de Erros.
| utp/ut-api-exec-custom.i | - PI interna a ser definida no programa (a mesma informada na include de rota correspondente);
- Programa de negócio a ser executado;
- PI interna do programa de negócio a ser executada;
- Tipo de Retorno do endpoint:
- "Object" = O conteúdo retornado pelo programa de negócio será um Objeto;
- "Array" = O conteúdo retornado pelo programa de negócio será um Array.
- Código do Endpoint que será utilizado para envio para EPC.
| Custom (NEG) | Tratativa especifica de negócio. | Para Tipo de Retorno "Object": - oInput (INPUT): Dados recebidos na requisição;
- oOutput (OUTPUT): Objeto retornado pelo programa de negócio;
- RowErrors (OUTPUT): Tempable de Erros.
Para Tipo de Retorno "Array": - oInput (INPUT): Dados recebidos na requisição;
- aResult (OUTPUT): Array retornado pelo programa de negócio;
- lHasNext (OUTPUT): Indicação se existem mais registros;
- RowErrors (OUTPUT): TempTable de Erros.
|
| Informações |
|---|
| - O programa de negócio informado será executado de forma persistente e executada a PI informada;
- A Include irá utilizar a classe utilitária JsonAPIExecution para realizar a execução do programa de negócio;
- As informações que serão envidas para a EPC, podem ser consultadas aqui.
|
>>>>>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 |
|---|
| language | ruby |
|---|
| theme | Eclipse |
|---|
| title | 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}
{utp/ut-api-exec-custom.i pi-send btb/progNeg.p pi-send-v1 "Array" "sendEmail"}
{utp/ut-api-exec-update.i pi-update btb/progNeg.p pi-update-v1}
{utp/ut-api-exec-get.i pi-find btb/progNeg.p pi-find-v1}
{utp/ut-api-exec-custom.i pi-default btb/progNeg.p pi-default-v1 "Object" "default"} |
| Bloco de código |
|---|
| language | ruby |
|---|
| theme | Eclipse |
|---|
| title | Programa de Negócio (btb/progNeg.p) |
|---|
| PROCEDURE pi-send-v1:
DEFINE INPUT PARAM oInput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM aResult AS JsonArray NO-UNDO.
DEFINE OUTPUT PARAM lHasNext AS LOGICAL NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR RowErrors.
DEFINE VARIABLE oObject AS JsonObject NO-UNDO.
aResult = NEW JsonArray().
oObject = NEW JsonObject().
oObject:ADD("teste", "teste").
oObject:ADD("teste1", "teste1").
oObject:ADD("teste2", "teste2").
aResult:ADD(oObject).
oObject = NEW JsonObject().
oObject:ADD("teste", "teste").
oObject:ADD("teste1", "teste1").
oObject:ADD("teste2", "teste2").
aResult:ADD(oObject).
ASSIGN lHasNext = NO.
END.
PROCEDURE pi-update-v1:
DEFINE INPUT PARAM oInput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM oOutput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR RowErrors.
oOutput = oInput.
END.
PROCEDURE pi-find-v1:
DEFINE INPUT PARAM oInput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM oOutput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM cExpandables AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR RowErrors.
oOutput = NEW JsonObject().
oOutput:ADD("method", "GET").
oOutput:ADD("procedure", "pi-find").
oOutput:ADD("description", "Test").
ASSIGN cExpandables = "tabFilha1,tabFilha2".
END.
PROCEDURE pi-default-v1:
DEFINE INPUT PARAM oInput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM oOutput AS JsonObject NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR RowErrors.
oOutput = NEW JSONObject().
oOutput:ADD("method", "GET").
oOutput:ADD("procedure", "pi-default").
oOutput: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. |
|
