Histórico da Página

...

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: /restlogix/wms/v1/dimensaodimensoes

Aviso

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

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

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

...

Informações

title	Importante

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

Image RemovedImage Added

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, adicionar um indicador ao nome do recurso "_espec" para que não gere conflitos com as APIs disponibilizadas pelo produto padrão.

Exemplo: obf_v1_transportadoratransportadoras_espec.4gl

Dentro do programa 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:

...

Image Added

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

...

Bloco de código

language	erl

DATABASE Logix

#------------------------------#
 FUNCTION wms_v1_dimensaodimensoes()
#------------------------------#
 
 	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_get_dimensaodimensoes_normal")  #--# Função a ser executada #--#
 	                                  
    CALL _ADVPL_add_rest_logix_routes("GET",                           
 	                                  "/*",                            
 	                                  "order=dimensao",                
 	                                  "wms_v1_get_dimensaodimensoes_ordenado")  
 	
 	CALL _ADVPL_add_rest_logix_routes("GET",                          
 	                                  "/*",                           
 	                                  "",                             
 	                                  "wms_v1_get_dimensaodimensoes")        
 	                             
 	CALL _ADVPL_add_rest_logix_routes("POST",                        
 	                                  "/*",                         
 	                                  "",                           
 	                                  "wms_v1_update_dimensaodimensoes")       
 	                                  
 	CALL _ADVPL_add_rest_logix_routes("PUT",                           
 	                                  "/*",                            
 	                                  "",                             
 	                                  "wms_v1_update_parc_dimensaodimensoes")  
 	                                  
    CALL _ADVPL_add_rest_logix_routes("DELETE",                       
 	                                  "/*",                          
 	                                  "",                            
 	                                  "wms_v1_delete_dimensaodimensoes")   
 
END FUNCTION


#------------------------------------------------------#
 FUNCTION wms_v1_get_dimensaodimensoes_normal(l_json_reference)
#------------------------------------------------------#

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

	RETURN l_json
	
END FUNCTION


#-------------------------------------------------------#
 FUNCTION wms_v1_get_dimensaodimensoes_ordenado(l_json_reference)
#-------------------------------------------------------#

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

	RETURN l_json
	
END FUNCTION

...

Bloco de código

language	erl

FUNCTION wms_v1_dimensaodimensoes()

É a função roteadora, que será executada pelo Logix REST quando feito uma requisição que combine com o módulo, a versão e o recurso da função.

Bloco de código

language	erl

CALL _ADVPL_create_rest_logix_routes()

...

Bloco de código

language	erl

CALL _ADVPL_add_rest_logix_routes("GET", #--# Método #--#
 	                              "/normal/*/", #--# Path Param #--#
 	                              "fields=*",   #--# QueryParam #--#
 	                              "wms_v1_get_dimensaodimensoes_normal")

Neste exemplo, está sendo definido uma rota, sendo que toda requisição de método GET, que contenha os filtros informados, será direcionado a função wms_v1_get_dimensao_normal.

...

Bloco de código

language	erl

CALL _ADVPL_add_rest_logix_routes("GET",                           
 	                              "/*",                            
 	                              "order=dimensao",                
 	                              "wms_v1_get_dimensaodimensoes_ordenado")

Neste exemplo, está sendo definido uma outra rota, sendo que toda requisição de método GET, que contenha qualquer parâmetro Path, um parâmetro Query "order" com valor "dimensao" será direcionado a função wms_v1_get_dimensaodimensoes_ordenado.

Bloco de código

language	erl

CALL _ADVPL_add_rest_logix_routes("GET",                          
 	                              "/*",                           
 	                              "",                             
 	                              "wms_v1_get_dimensaodimensoes")

Neste exemplo, todas as requisições de método GET, que possuírem quaisquer parâmetros (Query ou Path) informados, será direcionado para a função wms_v1_get_dimensaodimensoes.

Bloco de código

language	erl

CALL _ADVPL_add_rest_logix_routes("POST",                        
 	                              "/*",                         
 	                              "",                           
 	                              "wms_v1_update_dimensaodimensoes")

Neste exemplo, todas as requisições de método POST, que possuírem quaisquer parâmetros (Query ou Path) informados, será direcionado para a função wms_v1_update_dimensaodimensoes.

Informações

Algumas considerações sobre o uso de roteamento (_ADVPL_add_rest_logix_routes):

Os roteamentos devem ser definidos 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 interroga "?" como coringa de uma determinada posição e o "*" para um conjunto de caracteres variáveis (Mais detalhes na documentação da função: http://tdn.totvs.com/x/gZ1YDQ

Podem ser definidos mais de um parâmetro de pesquisa utilizando a vírgula "," como separador, e a pesquisa é sempre feita utilizado o operador AND.

...

LJSONOBJECT - Permite manipular o JSON recebido como parâmetro pela função. Documentação e exemplos:

Aviso

title	Importante

Para manipular as informações recebidas via JSON é importante a leitura da documentação referente ao LJSONOBJECT: LGX - LJSONOBJECT

LRestLogixResponse - Trata a criação do JSON de response da requisição.

Abaixo um exemplo alguns exemplos de utilização:

Bloco de código

language	erl
title	Criação de Response

#----------------------------------------------#
 FUNCTION wms_v1_get_dimensao(l_json_reference)
#----------------------------------------------#

	DEFINE l_json_reference VARCHAR(10)
    DEFINE l_logix_response VARCHAR(10)
	DEFINE l_json CHAR(1000)
	
    #--# Utilização do método SERIALIZE da classe LJSONOBJECT  #--#
	LET l_json = _ADVPL_get_property(l_json_reference,"SERIALIZE")
	
	#--# Criação da resposta padronizada utilizando a classe LRestLogixResponse  #--#
	LET l_logix_response = _ADVPL_create_component(NULL,"LRestLogixResponse")
    CALL _ADVPL_set_property(l_logix_response,"PAYLOAD",l_json,"payload")


	#--# Propriedades opcionais #--#
    CALL _ADVPL_set_property(l_logix_response,"MESSAGE","Erro Msg","Erro Detail", "10")
    CALL _ADVPL_set_property(l_logix_response,"STATUS",'200',"status")


	#--# Opcional, utilizada quando o conteúdo de retorno for um JSONArray #--#
	CALL _ADVPL_set_property(l_logix_response,"HAS_NEXT",TRUE)
    
	RETURN _ADVPL_get_property(l_logix_response,"GENERATE")

END FUNCTION

Bloco de código

language	erl
title	Carregando um Array de Record

      DEFINE l_json_data          CHAR(30000)
   DEFINE l_json_reference     VARCHAR(10)    
   DEFINE l_length_ajusts      SMALLINT
   DEFINE l_status             SMALLINT
   DEFINE l_ind                SMALLINT 
   
   DEFINE ma_ajust_bxa_adt_integ  ARRAY[500] OF RECORD
	                                               cod_tip_val      LIKE ad_valores.cod_tip_val,
	                                               valor            LIKE ad_valores.valor,
	                                               num_ad_nf_orig   LIKE adiant.num_ad_nf_orig,
	                                               ser_nf           LIKE adiant.ser_nf,
	                                               ssr_nf           LIKE adiant.ssr_nf,
	                                               cod_fornecedor   LIKE adiant.cod_fornecedor,
	                                               dat_mov          LIKE mov_adiant.dat_mov      
	                                            END RECORD                  
                                                                
   LET l_json_data = 
   '{
   		"payload": {
   		    "ajustBxaAdtInteg": [
	   		    {
	   		       "codTipVal": "1",
	   		       "valor": 1000,
	   		       "numAdNfOrig": 123456,
	   		       "serNf": "AD",
	   		       "ssrNF": "A",
	   		       "codFornecedor": "12",
	   		       "datMov": "10/10/2019"
	   		    },
	   		    {
	   		       "codTipVal": "2",
	   		       "valor": 3000,
	   		       "numAdNfOrig": 654321,
	   		       "serNf": "AF",
	   		       "ssrNF": "B",
	   		       "codFornecedor": "13",
	   		       "datMov": "01/12/2018"
	   		    },
	   		    {
	   		       "codTipVal": "3",
	   		       "valor": 2000,
	   		       "numAdNfOrig": 555555,
	   		       "serNf": "AJ",
	   		       "ssrNF": "C",
	   		       "codFornecedor": "14",
	   		       "datMov": "31/10/2019"
	   		    }
   		    ]
   		}
   }'
   
   LET l_json_reference = _ADVPL_create_component(NULL, "LJSONOBJECT")
   LET l_status         = _ADVPL_get_property(l_json_reference,"ACTIVATE",l_json_data CLIPPED)
   
   LET l_length_ajusts = _ADVPL_get_property(l_json_reference, "LENGTH", "payload/ajustBxaAdtInteg")    
    
   FOR l_ind = 1 TO l_length_ajusts
       
       LET ma_ajust_bxa_adt_integ[l_ind].cod_tip_val    = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/codTipVal")
       LET ma_ajust_bxa_adt_integ[l_ind].valor          = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/valor")
       LET ma_ajust_bxa_adt_integ[l_ind].num_ad_nf_orig = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/numAdNfOrig")
       LET ma_ajust_bxa_adt_integ[l_ind].ser_nf         = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/serNf")
       LET ma_ajust_bxa_adt_integ[l_ind].ssr_nf         = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/ssrNF")
       LET ma_ajust_bxa_adt_integ[l_ind].cod_fornecedor = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/codFornecedor")
       LET ma_ajust_bxa_adt_integ[l_ind].dat_mov        = _ADVPL_get_property(l_json_reference, "VALUE", "payload/ajustBxaAdtInteg["||l_ind||"]/datMov")
       
       CALL CONOUT("------------------- Exibindo os valores --------------------")
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].cod_tip_val)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].valor)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].num_ad_nf_orig)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].ser_nf)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].ssr_nf)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].cod_fornecedor)
       CALL CONOUT(ma_ajust_bxa_adt_integ[l_ind].dat_mov)
   
   END FOR

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: '{"queryParam1":["codigo","valor"]}'
	LET l_query_param = _ADVPL_get_property(l_json_reference,"VALUE","queryparams[1][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),'"}'
	
	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',"status")
    
	RETURN _ADVPL_get_property(l_logix_response,"GENERATE")

END FUNCTION

Páginas filhas

Versões comparadas

Versão antiga 14

Nova versão 15

Chave