...

     Para "publicar" a funcionalidade 4GL basta criar o programa (.4gl) com o seguinte caminho: <módulo>/api/<versão API>/<recurso>.4gl. A sub-pasta "api" passa então a concentrar todas as funcionalidades de integração do módulo em questão. Outros caminhos e parâmetros podem ser adicionados a URL, mas sempre de acordo com o Guia de Implementação de APIs.

Dentro        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 a partir do serviço web. Segue abaixo um exemplo de definição:

Sempre delimitada pelo caractere underscore, o nome da função indica como será sua estrutura a partir de cada delimitador, sendo:

1. Módulo da API (wms)
2. Versão da API (v1)
3. Recurso a ser executado (dimensao)

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

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

DATABASE Logix

#------------------------------#
 FUNCTION wms_v1_dimensao()
#------------------------------#
 
 	CALL _ADVPL_create_rest_logix_routes()
 	
 	CALL _ADVPL_add_rest_logix_routes("GET",                           #--# Método #--#
 	                                  "/normal/*/",                    #--# Path Param a ser filtrado #--#
 	                                  "fields=*",                      #--# Query ParamQueryParam a ser filtrado #--#
 	                                  "wms_v1_get_dimensao_normal")    #--# Função a ser executada #--#
 	                                  
    CALL _ADVPL_add_rest_logix_routes("GET",                           #--# Método #--#
 	                                  "/*",                            #--# Path Param a ser filtrado #--#
 	    
 	                                  "order=dimensao",                #--# Query Param a ser filtrado #--#
 	                                  "wms_v1_get_dimensao_ordenado")  #--# Função a ser executada #--#
 	
 	CALL _ADVPL_add_rest_logix_routes("GET",                           #--# Método #--#
 	                                  "/*",                            #--# Path Param a ser filtrado #--#
 	
 	                                  "",                              #--# Query Param a ser filtrado #--#
 	                                  "wms_v1_get_dimensao")           #--# Função a ser executada #--#
 	                             
 	CALL _ADVPL_add_rest_logix_routes("POST",                          #--# Método #--#
 
 	                                  "/*",                            #--# Path Param a ser filtrado #--#
 	                                  "",                              #--# Query Param a ser filtrado #--#
 	                                  "wms_v1_update_dimensao")        #--# Função a ser executada #--#
 	 
 	                                  
 	CALL _ADVPL_add_rest_logix_routes("PUT",                            #--# Método #--#
 	                                  "/*",                             #--# Path Param a ser filtrado #--#
 	                                  "",                             
 	  #--# Query Param a ser filtrado #--#
 	                                  "wms_v1_update_parc_dimensao")    #--# Função a ser executada #--#
 	                                  
    CALL _ADVPL_add_rest_logix_routes("DELETE",                         #--# Método #--#
 	                                  "/*",                          
 	  #--# Path Param a ser filtrado #--#
 	                                  "",                               #--# Query Param a ser filtrado #--#
 	                                  "wms_v1_delete_dimensao")   
      #--# Função a ser executada #--#
 
END FUNCTION

Abaixo seguem maiores detalhes sobre como o objeto de negócio e a URL de execução deverão ser criadas. 

1.1 Objeto de Negócio

O fonte que conterá a função principal (roteadora) deverá ser criado seguindo o padrão abaixo:

                                                           Image Removed

Exemplos:

...

1.2 Método de Execução

O método de execução indica como será realizada a chamada da função através de um serviço web, ou seja, qual método de requisição HTTP será utilizado para sua execução. Esta informação deve estar de acordo com o objetivo da função, indicando a ação que será realizada na mesma.

Abaixo segue a tabela de conversão dos métodos HTTP para o método de execução das funções 4GL:

...

PUT

...

END FUNCTION


#------------------------------------------------------#
 FUNCTION wms_v1_get_dimensao_normal(l_json_reference)
#------------------------------------------------------#

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

	RETURN l_json
	
END FUNCTION


#-------------------------------------------------------#
 FUNCTION wms_v1_get_dimensao_ordenado(l_json_reference)
#-------------------------------------------------------#

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

	RETURN l_json
	
END FUNCTION

No exemplo acima, temos os seguintes pontos:

FUNCTION wms_v1_dimensao()

    É 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.

CALL _ADVPL_create_rest_logix_routes()

    Inicia a técnica para definição das rotas de execução das funções conforme a requisição recebida.

CALL _ADVPL_add_rest_logix_routes("GET",                      #--# Método #--#
 	                          "/normal/*/",               #--# Path Param a ser filtrado #--#
 	                          "fields=*",                 #--# QueryParam a ser filtrado #--#
 	                          "wms_v1_get_dimensao_normal")  #--# Função a ser executada #--#

    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.

"/normal/*/",               #--# Path Param a ser filtrado #--#
"fields=*",                 #--# QueryParam a ser filtrado #--#

    Em relação ao filtro informado, será capturado todas as requisições que possuírem um parâmetro Path "/normal",  um parâmetro Query "fields" com qualquer conteúdo (*). 

CALL _ADVPL_add_rest_logix_routes("GET",                           
 	                          "/*",                            
 	                          "order=dimensao",                
 	                          "wms_v1_get_dimensao_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_dimensao_ordenado.

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

    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_dimensao.

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

   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çãowms_v1_update_dimensao.

Formato Mensagem JSON

...

      A referência a um LJSONOBJECT, recebido 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. Através desta mensagem, o desenvolvedor poderá efetuar os devidos filtros e lógicas necessárias. 

Exemplo de mensagem:

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

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:

• LJSONOBJECT - Permite manipular o JSON recebido como parâmetro pela função.
• LRestLogixResponse - Trata a criação do JSON de response da requisição.

Abaixo um exemplo de utilização:

#----------------------------------------------#
 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")
    
	RETURN _ADVPL_get_property(l_logix_response,"GENERATE")

END FUNCTION

Os métodos de requisições HTTP existentes podem ser consultados através deste link: http://www.w3schools.com/tags/ref_httpmethods.asp.

1.4 Nome da Função

O nome da função 4GL irá definir o entry point de execução através de um serviço web e indica o objeto de negócio que será manipulado.

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

...

FUNCTION logr0003_pub_create_inclusaoDimensao()

...

POST /logix-rest/logr3/inclusaoDimensao

...