CONTEÚDO
- Visão Geral
- Conceito
- Estrutura de Envio
- Estrutura de Respostas
- Exemplo de Configuração
- API REST disponíveis
- Catálogo de Produtos
- Catálogo de Produtos
- Assuntos relacionados
01. VISÃO GERAL
Disponibilizar recursos para facilitar a integração das rotinas do módulo Easy Import Control com a utilização da tecnologia de APIs REST.
02. CONCEITO
A integração via APIs REST permite a comunicação entre diferentes sistemas ou aplicativos por meio de APIs que seguem o padrão REST, onde essas APIs utilizam métodos HTTP padrão, como GET, POST, PUT e DELETE, com objetivo de permitir que sistemas compartilhem dados e funcionalidades de maneira eficiente e escalável.
Esses métodos são fundamentais para a comunicação entre clientes e servidores e cada um tem um propósito específico, como:
- GET: é usado para consultar algum dado do servidor, assim não realizando qualquer modificação neles, como por exemplo, uma consulta de cadastro.
- POST: é usado para enviar dados para serem processados ou armazenados no servidor, como por exemplo, uma inclusão de cadastro.
- PUT: é usado para atualizar algum dado do servidor, como por exemplo, uma alteração de cadastro.
- DELETE: é usado para remover algum dado do servidor. como por exemplo, uma exclusão de cadastro
Observação
Por padrão, para realizar o consulta de um determinado dado do servidor através do método GET, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64, caso contrário não informado, serão retornado os registros conforme sua paginação.
Exemplo:
"ICAgIDAwMDAwMDAwMDAwMDIyOA==" - representa a chave primária do registro da tabela da rotina em base64
http://localhost:8080/rest/FwModel/EICCP400/ICAgIDAwMDAwMDAwMDAwMDIyOA==
Para realizar a atualização de um determinado dado do servidor através do método PUT, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64, nesse caso, é obrigatório para realizar a alteração, caso contrário é entendido que está sendo feito uma inclusão.
Para realizar a exclusão de um determinado dado do servidor através do método DELETE, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64
03. ESTRUTURA DE ENVIO
A estrutura do JSON de envio (body) para os métodos GET e DELETE não tem necessidade de informar na requisição, somente realizar o consumo da API.
Já para o método POST e PUT, deverá ser enviado basicamente no formato:
{
"id": "ID_API",
"models": [{
"id": "MODELO_DADOS",
"modeltype": "FIELDS"
"fields": [{
"id": "CAMPO",
"order": 1,
"value": ""
}, {
"id": "CAMPO2",
"order": 2,
"value": "01"
}
],
"models": [{
"id": "SUBMODELO_DADOS",
"modeltype": "GRID"
"struct": [{
"id": "CAMPO",
"order": 1
}, {
"id": "CAMPO2",
"order": 2
}
],
"items": [{
"id": 1,
"fields": [{
"id": "CAMPO",
"value": "001"
}, {
"id": "CAMPO2",
"value": "01"
}
]
}, {
"id": 2,
"fields": [{
"id": "CAMPO",
"value": "002"
}, {
"id": "CAMPO2",
"value": "02"
}
]
}
],
}
],
}
]
}
Onde:
id: é id da API
models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC, que é definido por:
id: é o modelo de dados definido no MVC
modeltype: é tipo de modelo de dados, "FIELDS" ou "GRID"
fields: é um vetor com os campos do modelo, definido por:
id: é nome do campo
order: é a ordem do campo
value: é o valor do campo
models: é um vetor com os submodelos do modelo de dados do MVC, definido por:
id: é o submodelo de dados definido no MVC
modeltype: é tipo de modelo de dados, "FIELDS" ou "GRID"
struct: é um vetor definindo os campos do GRID, definido por:
id: é nome do campo
order: é a ordem do campo
items: é um vetor definindo os itens do GRID, definido por:
id: é um sequêncial do vetor dos itens,
fields: é um vetor com os campos e valores dos itens do GRID, definido por:
id: é nome do campo
value: é o valor do campo
04. ESTRUTURA DE RESPOSTAS
A estrutura do JSON de resposta para os métodos GET (para um determinado uma chave primária - pk), POST e PUT é basicamente da seguinte maneira:
{
"id": "ID_API",
"pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
"models": []
}
Onde:
id: é id da API
pk: chave primária de cada registro para realizar uma consulta específica, consumir o método put e delete
models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC (FIELDS, GRID)
A estrutura do JSON de resposta para o método GET sem determinar uma chave primária (pk), será da seguinte maneira:
{
"total": 82,
"count": 10,
"startindex": 1,
"resources": [{
"id": "ID_API",
"pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
"models": []
}, {
"id": "ID_API",
"pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
"models": []
}
]
}
Onde:
total: é o total de registros que existem no sistema
count: é a quantidade de registros retornados na requisição
startindex: é a contador inicial para realizar a paginação
resources: são as informações dos modelos de dados da API, composto por:
id: é id da API
pk: chave primária de cada registro para realizar uma consulta específica, consumir o método put e delete
models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC (FIELDS, GRID)
A estrutura do JSON de resposta para o método DELETE da seguinte maneira:
true
A estrutura do JSON de resposta com falha, será da seguinte maneira:
{
"errorCode": 400,
"errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[EK9MASTER]\r\nId campo origem:[EK9_COD_I]\r\nId submodelo erro: [EK9MASTER]\r\nId campo erro: [EK9_COD_I]\r\nId erro: [JAGRAVADO ]\r\nMensagem de erro: [ Já existe registro com esta informação.]\r\nMensagem da solução: [Troque a chave principal deste registro.\r\n]\r\nValor atribuído: []\r\nValor anterior: [4234234290 ]\r\n"
}
05. EXEMPLO DE CONFIGURAÇÃO
Abaixo um exemplo de configuração do arquivo appserver.ini
Exemplo de configuração appserver.ini
[HTTPV11] Enable=1 Sockets=HTTPREST [HTTPREST] Port=8080 URIs=HTTPURI SECURITY=1 [HTTPURI] URL=/rest PrepareIn=99,01 Instances=1,2 [ONSTART] jobs=HTTPJOB RefreshRate=120 [HTTPJOB] MAIN=HTTP_START ENVIRONMENT=ENVIRONMENT
06. API REST DISPONÍVEIS
Após a configuração do REST do Protheus, podemos verificar todas as APIs REST disponível:
- acessar o endereço configurado do Rest, nesse exemplo foi configurado dessa forma http://localhost:8080/rest
- procurar o serviço FWMODEL
- clicar em /rest/fwmodel.catalog.
Será apresentado o catálogo de API REST disponíveis para as rotinas do Protheus:
Para realizar o consumo de uma API REST disponíveis do módulo de Easy Import Control, deverá ser da seguinte forma:
http://localhost:8080/rest/FwModel/EICCP400
Onde:
http://localhost:8080/rest é o endereço configurado do REST
/FwModel é fixo (framework)
/EICCPP400 é nome da API disponível, nesse exemplo, é a rotina de catálogo de produto
As APIs REST disponíveis do módulo Easy Import Control:
07. ASSUNTOS RELACIONADOS
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas