Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

CONTEÚDO

  1. Visão Geral
  2. Conceito
  3. Estrutura de Envio
  4. Estrutura de Respostas
  5. Exemplo de Configuração
  6. API REST disponíveis
    1. Catálogo de Produtos
  7. 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.

Image Added

Será apresentado o catálogo de API REST disponíveis para as rotinas do Protheus:

Image Added


Para realizar o consumo de uma API REST disponíveis do módulo Financeiro, deverá ser da seguinte forma:

http://localhost:8080/rest/FwModel/FINA040VA

Onde:

http://localhost:8080/rest é o endereço configurado do REST

/FwModel é fixo (framework)

/FINA040VA é nome da API disponível, nesse exemplo, é a rotina de catálogo de produto

07. ASSUNTOS RELACIONADOS