Conceito
...
Uma API (acrônimo de Application Programming Interface ou Interface de Programação de Aplicação em português) é um conjunto de rotinas e padrões estabelecidos por um software para a utilização de seus recursos por aplicativos que não pretendem envolver-se em detalhes da implementação do software, mas apenas usar seus serviços. De modo geral, uma API é composta por uma série de funções acessíveis somente por programação e que permitem utilizar características do software menos evidentes ao usuário tradicional.
| Informações |
|---|
No desenvolvimento do produto Logix uma API antigamente chamava-se RNL acrônimo de Regra de Negócio Logix. |
Desenvolvimento
...
Para o correto desenvolvimento é preciso ter em mente alguns cuidados que devem ser sempre considerados na construção de uma API:
...
Nos próximos itens deste documento, serão detalhadas as técnicas que devem ser seguidas na construção do código fonte da API.
Clique AQUI para obter o código 4GL base de uma API para desenvolvimento e complemente o código conforme a necessidade da sua API.
| Aviso |
|---|
|
Utilize sempre como base para a criação de uma API TOTVS o Guia de Implementação de API TOTVS, disponível em: http://tdn.totvs.com/x/nDUxE |
...
| Expandir |
|---|
| title | Clique para expandir e ver o exemplo... |
|---|
|
| Bloco de código |
|---|
| language | ruby |
|---|
| theme | Confluence |
|---|
| DATABASE Logix
{#
#Função roteadora principal 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.
#}
#---------------------------#
FUNCTION wms_v1_dimensoes()
#---------------------------#
{DEFINIÇÃO DAS ROTAS}
#Inicia a técnica para definição das rotas de execução das funções conforme a requisição recebida.
CALL _ADVPL_create_rest_logix_routes()
#Definição de rota onde toda requisição de método GET, que contenha o filtro a seguir,
#será direcionada para função wms_v1_dimensoes_get_normal().
#FILTRO:
# - Serão capturadas todas as requisições que possuírem um parâmetro Path "/normal"
# e um parâmetro Query "fields" com qualquer conteúdo (*).
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 #--#
#Definição de outra rota, onde toda requisição de método GET, que contenha o filtro a seguir,
#será direcionada para função wms_v1_dimensoes_get_ordenado().
#FILTRO:
# - Serão capturadas todas requisições que contenha qualquer parâmetro Path ("/*" indica "Todos Paths" ou "nenhum")
# e um parâmetro Query "order" com valor "dimensao"
CALL _ADVPL_add_rest_logix_routes("GET",
"/*",
"order=dimensao",
"wms_v1_dimensoes_get_ordenado")
#Definição de outra rota, onde todas as requisições de método GET, que possuírem quaisquer parâmetros
#(Query e/ou Path) informados, serão direcionadas para a função wms_v1_dimensoes_get().
CALL _ADVPL_add_rest_logix_routes("GET",
"/*",
"",
"wms_v1_dimensoes_get")
#Definição de rota onde todas as requisições de método POST, que possuírem quaisquer parâmetros (Query e/ou Path) informados,
#serão direcionadas para a função wms_v1_dimensoes_post().
CALL _ADVPL_add_rest_logix_routes("POST",
"/*",
"",
"wms_v1_dimensoes_post")
#Definição de rota onde todas as requisições de método PUT (update), que possuírem quaisquer parâmetros (Query e/ou Path) informados,
#serão direcionadas para a função wms_v1_dimensoes_put().
CALL _ADVPL_add_rest_logix_routes("PUT",
"/*",
"",
"wms_v1_dimensoes_put")
#Definição de rota onde todas as requisições de método DELETE, que possuírem quaisquer parâmetros (Query e/ou Path) informados,
#serão direcionadas para a função wms_v1_dimensoes_delete().
CALL _ADVPL_add_rest_logix_routes("DELETE",
"/*",
"",
"wms_v1_dimensoes_delete")
END FUNCTION
#------------------------------------------------------#
FUNCTION wms_v1_dimensoes_get_normal(l_json_reference)
#------------------------------------------------------#
#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
|
|
IMPORTANTE
| Dica |
|---|
Para PATH com valor obrigatório informe ?* (interrogação seguido de asterisco), que determina que o PATH tem ao menos 1 caracter qualquer (?), seguido de 0 ou mais caracteres (*). Exemplo: "/normal/?*/", #--# Path Param obrigatório a ser filtrado #--# |
OBSERVAÇÕES
| 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=* |
...
Através desta mensagem, o desenvolvedor poderá efetuar os devidos filtros e lógicas necessárias.
EXEMPLO DE MENSAGEM JSON
| Bloco de código |
|---|
| language | js |
|---|
| theme | Confluence |
|---|
|
{
uri: valor,
method: GET,
headers: {},
pathParams: [ "param1", "param2" ],
queryParams: { query1: valor1, query2: valor1},
payload: {}
} |
06.
...
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:
...
07. Exemplo de montagem do JSON de retorno
EXEMPLO MONTAGEM DO JSON DE RETORNO DA REQUISIÇÃO
| Expandir |
|---|
| title | Clique para expandir e ver o exemplo... |
|---|
|
| Bloco de código |
|---|
| language | ruby |
|---|
| theme | Confluence |
|---|
| title | Criação de Response |
|---|
| linenumbers | true |
|---|
| #-----------------------------------------------#
FUNCTION wms_v1_dimensoes_get(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 (mensagem de erro, detalhamento do erro, código do erro #--#
CALL _ADVPL_set_property(l_logix_response,"MESSAGE","Mensagem de erro","Detalhamento do erro", "10")
#--# Definição do status de retorno da requisição
CALL _ADVPL_set_property(l_logix_response,"STATUS",'200')
#--# Opcional, utilizada quando o conteúdo de retorno for um JSONArray #--#
CALL _ADVPL_set_property(l_logix_response,"HAS_NEXT",TRUE)
#Retorno do conteúdo do componente LRestLogixResponse no formato JSON
RETURN _ADVPL_get_property(l_logix_response,"GENERATE")
END FUNCTION |
|
...
08. Exemplo de leitura dos dados da requisição
EXEMPLO DE LEITURA DOS DADOS ENVIADOS NO JSON DA REQUISIÇÃO
A leitura dos dados do JSON da requisição é realizada utilizando a função _ADVPL_get_property(l_json_reference, "VALUE",<campo>)
...
09. Exemplo de leitura dos filtros da requisição (QueryParam e PathParam)
EXEMPLO DA LEITURA DOS FILTROS QueryParam E PathParam ENVIADOS NO JSON DA REQUISIÇÃO
| Expandir |
|---|
| title | Clique para expandir e ver o exemplo... |
|---|
|
| Bloco de código |
|---|
| language | ruby |
|---|
| theme | Confluence |
|---|
| 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 |
|
...
