Esta página apresenta e descreve a técnica (framework, ferramental e tecnologias) utilizados para o desenvolvimento de APIs padrões (serviços públicos) em produtos TOTVS Agro, com foco em TOTVS Agro Bioenergia.
Este material menciona "TOTVS Agro API Hub", como o framework, ferramental e tecnologias necessárias para a construção e a exposição de APIs padrões (serviços públicos), bem como o "TOTVS Agro Middleware", que representa um serviço/componente intermediário para camada de adaptadores (adapter), como transformações, regras de negócio e outras implementações específicas.
O projeto ta-api-hub é uma ferramenta desenvolvida para facilitar a exposição de APIs de forma facilitada e padronizada, com base na estrutura de dados das soluções TOTVS Agro (Bioenergia), possibilitando também customizar as APIs via cadastro de queries obtendo maior flexibilidade.
O Cadastro de Entidades e Queries definirá a configuração / exposição e comportamento das APIs, bem como os métodos HTTPs habilitados, tabelas e colunas utilizadas, atributos da estrutura JSON relacionada, validações básicas, como tamanho, tipo de dado, obrigatoriedade, aplicação de máscara, validação de existência de entidade relacionada.
A disponibilização das APIs no ta-api-hub é realizada via cadastro de entidades, definida e baseada na estrutura de dados da aplicação, conforme os cadastros a seguir:
Endpoint para entidades:
Estrutura de dados:
{
"id": "UUID",
"name": "nomeEntidade",
"description": "Descrição da Entidade",
"product": "BIOENERGIA",
"entityTable": "NOME_DA_TABELA",
"lastUpdate": "2024-06-20T12:58:05.401",
"entityDeList": [
{
"id": "UUID",
"fieldName": "nomeDoCampo",
"description": "Descricao do Campo",
"tableColumn": "NOME_DA_COLUNA",
"columnType": "STRING",
"columnSize": 50,
"columnRequired": true,
"columnMask": null,
"columnPk": true,
"tableFk": null,
"columnFk": null,
"filter": true
},
...
],
"entityChildList": [
{
"id": "UUID",
"entityChild":{}
"entityChildType": ""
},
...
],
"entityApi": {
"id": "UUID",
"pathUrl": "entidades",
"apiVersion": "v1",
"businessClass": "",
"enableGet": true,
"enablePost": true,
"enablePut": true,
"enableDelete": true,
"enabled": true,
"lastUpdate": "2024-06-20T12:58:05.401"
}
} |
Diponibilizado endpoint para consulta do sumário de entidades cadastradas.
Método GET
[
{
"id": "a3427359-dc2f-4245-915c-972cfa2b25af",
"name": "parametro",
"description": "Parametros",
"path": "api/entity/v1/parametros",
"enableGet": true,
"enablePost": false,
"enablePut": false,
"enableDelete": false,
"enabled": true,
"details": [
{
"id": "d4a0e418-9423-4516-940b-03d4de5b9800",
"fieldName": "secao",
"description": "Seção",
"columnRequired": false,
"columnPk": false,
"filter": true
},
{
"id": "6c076bf9-2456-4b46-b43a-1296047be0ab",
"fieldName": "entrada",
"description": "Entrada",
"columnRequired": false,
"columnPk": false,
"filter": true
},
{
"id": "87c60f83-7592-44d7-9005-43589a05dcda",
"fieldName": "tipo",
"description": "Tipo",
"columnRequired": false,
"columnPk": false,
"filter": false
},
{
"id": "2fe199e6-3209-463b-af31-1ef20794e2b5",
"fieldName": "valor",
"description": "Valor",
"columnRequired": false,
"columnPk": false,
"filter": false
},
{
"id": "0611d39b-42f8-4044-86db-bb9e6336c998",
"fieldName": "descricao",
"description": "Descrição",
"columnRequired": false,
"columnPk": false,
"filter": true
},
{
"id": "828fcde4-9d47-4270-b1a7-82f35f148517",
"fieldName": "validos",
"description": "Valores Válidos",
"columnRequired": false,
"columnPk": false,
"filter": false
},
{
"id": "a4802480-ed33-46b6-91c1-df0e442672ac",
"fieldName": "instancia",
"description": "Instancia",
"columnRequired": false,
"columnPk": false,
"filter": true
}
]
},
...
] |
A disponibilização das APIs no ta-api-hub também podes ser realizada via cadastro de queries, definida e baseada na estrutura de dados da aplicação, conforme os cadastros a seguir:
Endpoint para queries:
Estrutura de dados:
[
{
"id": "UUID",
"name": "nomeEstruturaDados",
"description": "Descrição",
"product": "BIOENERGIA",
"pathUrl": "queries",
"lastUpdate": "2024-06-20T04:58:05.401",
"queryDeList": [
{
"id": "UUID",
"apiVersion": "v1",
"query": "SELECT CD_SAFRA, DE_SAFRA, DE_COMP_TBL FROM SAFRAS WHERE CD_SAFRA = ::codigo",
"databaseType": "ORACLE",
"httpMethod": "GET",
"enabled": true
},
...
],
"queryFieldsList": [
{
"fieldName": "codigo",
"tableColumn": "CD_SAFRA",
"columnType": "INTEGER",
"columnSize": 5,
"columnRequired": true,
"columnMask": null,
"columnPk": true,
"tableFk": null,
"columnFk": null,
"id": "697e73b0-9520-4819-a6dc-350172fd9792"
},
...
]
}
] |
Diponibilizado endpoint para consulta do sumário de queries cadastradas.
Método GET
[
{
"id": "ce429b8e-e284-44c7-a37c-d7dfbb0b7aed",
"name": "safra",
"description": "Safras",
"details": [
{
"id": "56c53717-727b-4b33-bfcd-57b6f85d20df",
"query": "SELECT CD_SAFRA, DE_SAFRA, DE_COMP_TBL FROM SAFRAS WHERE CD_SAFRA = ::codigo",
"httpMethod": "GET",
"path": "/api/v1/safras",
"enabled": true
},
{
"id": "bf3bbf43-cb35-4cc7-8c50-4c441772d4ce",
"query": "INSERT INTO SAFRAS(CD_SAFRA, DE_SAFRA, DE_COMP_TBL) VALUES (::codigo,::descricao,::complemento)",
"httpMethod": "POST",
"path": "/api/v1/safras",
"enabled": true
},
{
"id": "23856856-2b8b-48a4-988d-38a20dba7209",
"query": "UPDATE SAFRAS SET DE_SAFRA = ::descricao, DE_COMP_TBL = ::complemento WHERE CD_SAFRA = ::codigo",
"httpMethod": "PUT",
"path": "/api/v1/safras",
"enabled": true
},
{
"id": "4ddbba69-91a3-4f6e-92c3-92cd24a8619a",
"query": "DELETE FROM SAFRAS WHERE CD_SAFRA = ::codigo",
"httpMethod": "DELETE",
"path": "/api/v1/safras",
"enabled": true
}
]
}
] |
A URL para as entidades e queries cadastradas é composta confome conforme configurado no cadastro da EntityAPI e QueryHe/QueryDe, para os campos apiVersion e pathUrl, conforme demonstrado a seguir:
Os métodos HTTPs que podem ser utilizados são GET, POST, PUT e DELETE, e estarão disponíveis conforme configurados em cada modelo de exposição de APIs.
A autenticação/autorização das APIs de integração utiliza o OAuth 2.0 Client Credentials Grant, sendo o método mais utilizado e também um fluxo de autorização projetado especificamente para integrações entre sistemas backend.
Principais vantagens:
Fluxo:
Este tópico visa descrever o processo e as tecnologias utilizadas no desenvolvimento do TOTVS Agro Middleware. Utilizamos Java 21 pela sua robustez e eficiência, aliado à versão mais recente do Spring Framework, que oferece uma vasta gama de funcionalidades para a construção de aplicações modernas. Para simplificar a configuração, utilizamos traduções de XML baseadas em anotações, permitindo uma manutenção mais intuitiva e menos redundante. Além disso, implementamos um sistema de controle de filas lógicas e monitoramento de status para assegurar a integridade e a eficiência dos processos assíncronos. Essa combinação de tecnologias e práticas nos permite desenvolver uma aplicação escalável, segura e de alto desempenho.
Vídeos para exemplificar o fluxo completo da Integração entre Fila EAI x TOTVS Agro Middleware x TOTVS Agro API Hub
Release 12.1.2406 (Junho/2024)