Histórico da Página

Informações

title	Índice

Índice

style	circle

01. Introdução

O desenvolvimento de APIs permite a exposição e o consumo de dados para integração (front-end, portais, customizações, etc) com o back-end do produto Logix, de maneira segura e padronizada.

...

Informações

title	Matriz de Evolução

Versão / Release

Funcionalidade

12.1.22

Requisições através dos verbos GET / POST / PUT / DELETE utilizando o contexto /restlogix

Classe utilitária para tratamento das respostas da requisição (response) em 4GL.

12.1.24

Requisições através dos verbos GET / POST / PUT / DELETE utilizando o contexto /api

Classe utilitária para tratamento das respostas da requisição (response) em 4GL.

O contexto /restlogix está em processo de depreciação.

02. Formato URL

O Guia de Implementação de API TOTVS define que o formato das URIs dos endpoints devem conter o nome do produto, o módulo, a versão da API e o recurso alvo da funcionalidade em questão. Tomando como exemplo o endpoint de integração do recurso de "Dimensões" do módulo de "WMS" do produto "Logix", a URI básica deste serviço deve ser: /api/wms/v1/dimensoes

...

Aviso

A URL definida pelo Padrão de API TOTVS segue o seguinte formato:

/api/<módulo>/<versão API>/<recurso>/

Informações que forem passadas após o recurso, serão tratadas como parâmetros PATH.

03. Serviços 4GL

Para "publicar" a funcionalidade 4GL basta criar o programa (.4gl) com o seguinte caminho: <módulo>/api/<versão API>/<recurso>.4gl.

...

Informações

title	Importante

Os programas 4GL disponibilizados, deverão seguir o padrão de localização abaixo:

Image Modified

Exemplos:

Objeto de Negócio	Função de roteamento
\suprimentos\obrigacoes_fiscais\api\v1\transportadoras.4gl	obf_v1_transportadoras
\suprimentos\suprimentos\api\v1\estoque.4gl	sup_v1_estoque
\adm_producao\manufatura\api\v1\apontamento_horas.4gl	man_v1_apontamento_horas

Nota

title	Importante

Para desenvolvimentos específicos é preciso adicionar o sufixo "_espec" ao nome do recurso para que não gere conflitos com as APIs padrões disponibilizadas pelo produto.

Exemplo: obf_v1_transportadoras_espec.4gl

Dentro do código fonte 4GL a definição da função principal (roteadora) é de fundamental importância, pois é ela que será primeiramente chamada e que definirá como será a execução das outras funções com base na requisição solicitada. Segue abaixo um exemplo de definição:

Informações
Image Modified

04. Exemplo de desenvolvimento em 4GL

Nome das funções

Exemplo de definição de funçõe756pxs funções e como será realizada a requisição web de execução destas funções:

...

Função	Requisição
`FUNCTION obf_v1_transportadoras()`	`GET/POST/PUT/DELETE /api/obf/v1/transportadoras`
`FUNCTION sup_v1_estoque()`	`GET/POST/PUT/DELETE /api/sup/v1/estoque`
`FUNCTION man_v1_apontamento_horas()`	`GET/POST/PUT/DELETE /api/man/v1/apontamento_horas`

Abaixo um exemplo de recurso desenvolvido em 4GL para ser utilizado junto ao serviço de API:

Bloco de código

language	ruby
theme	erlConfluence

DATABASE Logix

#---------------------------#
 FUNCTION wms_v1_dimensoes()
#---------------------------#
{FUNÇÃO PRINCIPAL QUE FAZ DEFINIÇÃO DAS ROTAS}

 	CALL _ADVPL_create_rest_logix_routes()
 	
 	CALL _ADVPL_add_rest_logix_routes("GET",                      #--# Método #--#
 	                                  "/normal/*/",               #--# Path Param a ser filtrado #--#
 	                                  "fields=*",                 #--# QueryParam a ser filtrado #--#
 	                                  "wms_v1_dimensoes_get_normal")  #--# Função a ser executada #--#
 	                                  
    CALL _ADVPL_add_rest_logix_routes("GET",                           
 	                                  "/*",                            
 	                                  "order=dimensao",                
 	                                  "wms_v1_dimensoes_get_ordenado")  
 	
 	CALL _ADVPL_add_rest_logix_routes("GET",                          
 	                                  "/*",                           
 	                                  "",                             
 	                                  "wms_v1_dimensoes_get")        
 	                             
 	CALL _ADVPL_add_rest_logix_routes("POST",                        
 	                                  "/*",                         
 	                                  "",                           
 	                                  "wms_v1_dimensoes_post")       
 	                                  
 	CALL _ADVPL_add_rest_logix_routes("PUT",                           
 	                                  "/*",                            
 	                                  "",                             
 	                                  "wms_v1_dimensoes_put")  
 	                                  
    CALL _ADVPL_add_rest_logix_routes("DELETE",                       
 	                                  "/*",                          
 	                                  "",                            
 	                                  "wms_v1_dimensoes_delete")   
END FUNCTION

#------------------------------------------------------#
 FUNCTION wms_v1_dimensoes_get_normal(l_json_reference)
#------------------------------------------------------#
	DEFINE l_json_reference VARCHAR(10)
	DEFINE l_json VARCHAR(1000)
	
	{FUNÇÃO GET COM PATH PARAM "NORMAL" ADICIONADA COMO ROTA NA FUNÇÃO wms_v1_dimensoes()}

	DEFINE l_json_reference VARCHAR(10)
	DEFINE l_json VARCHAR(1000)
	
	.
	.
	.

	RETURN l_json
END FUNCTION


#-------------------------------------------------------#
 FUNCTION wms_v1_dimensoes_get_ordenado(l_json_reference)
#-------------------------------------------------------#
{FUNÇÃO GET COM PATH PARAM "ORDENADO" ADICIONADA COMO ROTA NA FUNÇÃO wms_v1_dimensoes()}

	DEFINE l_json_reference VARCHAR(10)
	DEFINE l_json VARCHAR(1000)
	
	.
	.
	.

	RETURN l_json
END FUNCTION

No exemplo acima, temos os seguintes pontos:

01. Função Roteadora

Bloco de código

language	erl

FUNCTION wms_v1_dimensoes()

...

Informações

Algumas considerações sobre o uso de roteamento através da função _ADVPL_add_rest_logix_routes():

Os roteamentos devem ser definidos sempre do mais específico (detalhado) para o mais genérico (simples).

O Logix REST utiliza a função Match() do ADVPL, que basicamente permite o uso do sinal "?" (interrogação) como coringa para uma determina um único caracter obrigatório e o sinal "*" (asterisco) para um conjunto de caracteres variáveis (zero ou mais caracteres). Neste caso, quando houver necessidade de ter ao menos 1 caracter obrigatório, deve-se informar "?*" que determinará "1 ou mais caracteres" e quando informar "*" (apenas asterisco) determinará "0 ou mais caracteres". Para mais detalhes acesse a documentação da função Match().

Podem ser definidos um ou mais parâmetros de pesquisa utilizando a "," (vírgula) como separador e a pesquisa sempre será realizada utilizando o operador AND.
Exemplo:
```
CALL _ADVPL_add_rest_logix_routes("GET",                           
 	                              "/*",                            
 	                              "order=dimensao,cliente=*",                
 	                              "wms_v1_get_dimensoes_ordenado")
```
Veja que o parâmetro QUERY foi repassado como "order=dimensao,cliente=*" onde existem 2 filtros separados por uma vírgula, sendo:

FILTRO 1: order=dimensao

FILTRO 2: cliente=*

Atente aos valores repassados como QUERY e PATH pois são processados como CaseSensitve.

03. Formato

...

Mensagem JSON

A varíavel de referência de um objeto LJSONOBJECT, recebida pela requisição na função 4GL conterá informações completas da requisição, desde informações do HEADER, QUERY PARAMs, PATH PARAMs e o próprio PAYLOAD.

...

Bloco de código

language	js

{ 
    uri: valor,
	method: GET,
    headers: {},
	pathParams: [ "param1", "param2" ],
	queryParams: { query1: valor1, query2: valor1},
	payload: {}
}

03. Classes

...

Utilitárias

...

Com o objetivo de facilitar a manipulação dos objetos JsonObject recebidos e enviados pela API 4GL, foram desenvolvidas algumas classes de utilitários:

...

Bloco de código

language	erl
title	Carregar QueryParam e PathParam

#--------------------------------------------------#
 FUNCTION vdp_v1_clientes_nacionais(l_json_reference)
#--------------------------------------------------#
    DEFINE l_json_reference VARCHAR(10)
    DEFINE l_logix_response VARCHAR(10)
	DEFINE l_query_param CHAR(200)
	DEFINE l_path_param  CHAR(200)
	DEFINE l_json_retorno CHAR(1000)
	
    #--# Carrega o valor da primeira entrada do Query Param #--# 
    #--# Exemplo de QueryParams ?order=dimensao&cliente=1234: '[["order","dimensao"],["cliente","1234"]]'
    #--# No exemplo abaixo, a busca acontece no primeiro QueryParam (order) buscando o nome dele (order) #--#
	LET l_query_param = _ADVPL_get_property(l_json_reference,"VALUE","queryparams[1][1]") 
    #--# Neste exemplo, a busca acontece no primeiro QueryParam (order) buscando o valor dele (dimensao) #--#
	LET l_query_param = _ADVPL_get_property(l_json_reference,"VALUE","queryparams[1][2]") 
    #--# No exemplo abaixo, a busca acontece no segundo QueryParam (cliente) buscando o nome dele (cliente) #--#
	LET l_query_param = _ADVPL_get_property(l_json_reference,"VALUE","queryparams[2][1]") 
    #--# Neste exemplo, a busca acontece no primeiro QueryParam (cliente) buscando o valor dele (1234) #--#
	LET l_query_param = _ADVPL_get_property(l_json_reference,"VALUE","queryparams[2][2]")
	
	#--# Carrega o primeiro Path Param #--# 
    #--# Exemplo: '{"pathparams":["path1","path2"]}'
	LET l_path_param = _ADVPL_get_property(l_json_reference,"VALUE","pathparams[1]") 
	
	LET l_json_retorno = '{"queryParam":"',LOG_alltrim(l_query_param),'","pathParam":"',LOG_alltrim(l_path_param),'"}'
	
	#--# Executar a regra de negócio neste ponto #--# 
	LET l_logix_response = _ADVPL_create_component(NULL,"LRestLogixResponse")
    CALL _ADVPL_set_property(l_logix_response,"PAYLOAD",l_json_retorno,"payload")
    CALL _ADVPL_set_property(l_logix_response,"STATUS",'200')
    
	RETURN _ADVPL_get_property(l_logix_response,"GENERATE")
END FUNCTION

Card documentos

Informacao	Após configuração do usuário Logix e/ou Empresa na seção [WEBSERVICES], conforme mencionado acima, reinicie o AppServer para que a nova configuração seja levada em consideração nas requisições REST e WebServices no Logix.
Titulo	IMPORTANTE!

Templatedocumentos

Autor	Framework

HTML

<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>

Páginas filhas

Versões comparadas

Versão antiga 35

Nova versão 36

Chave

01. Introdução

02. Formato URL

03. Serviços 4GL

04. Exemplo de desenvolvimento em 4GL

Nome das funções

01. Função Roteadora

03. Formato

Mensagem JSON

03. Classes

Utilitárias