DEV Community: Josimar Junior

Um microblog usando Protheus - Rest Server, parte 5, GET e query parameters

Josimar Junior — Sat, 26 Dec 2020 20:32:53 +0000

Introdução

Seguindo com a exploração dos modelos para construção dos métodos de apis utilizando Advpl no Rest Protheus, nesta publicação será abordado como fazer uso dos recursos de query parameters e assim permitir pesquisa e exploração das informações no ERP.

Na publicação anterior os métodos POST na uri /perfis e GET, DELETE e PUT na uri /perfis/:id foram modificados para utilizar o modelo de dados do MVC Advpl como camada de interação com o banco de dados, o link para a publicação anterior está aqui.

Entretanto um dos endpoints muito usado até então não foi modificado, o GET na uri /perfis. Este é o endpoint onde é conseguida a lista dos recursos oferecidos pela api. Essa modificação não aconteceu no passo anterior, pois não é possível realizar a recuperação de uma lista usando um modelo de dados que foi desenvolvido para lidar com um único registro.

Em função disso, será mostrada uma alternativa de como implementar de forma simplificada:

filtros utilizando expressões SQL limitadas a partir de dados informados na api;
restrição das propriedades a serem retornadas, reduzindo o tamanho da resposta;
paginação dos dados da api, essencial para avaliação de quantidade de itens e;
definição da ordem dos dados na requisição.

Deve ser ressaltado que a escolha de demonstrar a implementação desses recursos não assegura que o código resultante esteja pronto para apis que tenham necessidades avançadas, seja de desempenho, seja de complexidade da lógica de negócio envolvida. O código construído tem o objetivo de ser claro e mostrar exatamente onde as regras são extraídas e como são transformadas em cada um dos recursos.

Por que desenvolver estes recursos?

Quando endpoints que oferecem a possibilidade de listagem dos itens não possuem flexibilidade de filtro ou pesquisa, é bem ruim ser um cliente dessa api, afinal todo o trabalho manipulação dos dados para exibição fica como responsabilidade do cliente, portanto, oferecer recursos para filtrar e controlar quais e como as propriedades devem ser retornadas é essencial para ser uma boa api.

A Totvs possui um guia de implementação de apis para ser utilizado pelos times internamente e especificamente sobre retorno de coleções pode ser lido e avaliado aqui. O guia não será seguido nesta série apesar de várias semelhanças poderem ser identificadas.

A implementação

Os recursos mencionados e criados para permitir a manipulação do retorno da coleção de GET /perfis/ foram:

paginação: permitir que uma quantidade limitada de perfis sejam retornados por requisição no endpoint, o principal benefício é que um cliente consegue então exibir uma lista menor mais rápido e caso precise carregue mais itens com uma quantidade maior depois;
ordenação: conseguir pelo cliente indicar a ordem que os resultados devem ser retornados, um exemplo é a ordenação por nome ou por data de criação que são usadas por razões diferentes no cliente, deixar a ordem fixa poderia atender somente uma das formas de uso;
projeção de retorno: quando necessário os valores de somente uma ou duas propriedades de um certo endpoint, recuperar todas as propriedades e usar somente o que precisava é desperdício de recurso;
filtro: este é um aspecto delicado, enquanto é um excelente recurso e provavelmente o mais necessário, oferecer essa possibilidade implica em cuidado extra para evitar códigos maliciosos serem injetados no programa durante a execução.
contagem: quando filtro é permitido no endpoint, a contagem passa a ter complicações para execução, pois o filtro precisa ser considerado também. O principal objetivo da contagem é indicar que existem ou não mais itens para carregar pelo cliente.

A seguir os detalhes da implementação dos recursos, de forma simplificada mostrando como que o Rest Protheus oferece e como fazer em Advpl.

A base

Para a construção destes recursos a primeira alteração foi trocar a iteração sobre a tabela ZT0 com while e DbSkip para a execução de uma consulta SQL na recuperação dos perfis a serem retornados. O ganho com esta simples alteração é a possibilidade de construção dinâmica da query, com os cuidados especiais para não causar quebras por entradas incorretas informadas na requisição.

A implementação mostrada ainda pode ter quebras em condições bem específicas de uso, então se tem a intenção de usar como base para sua api, teste bem!

oPrepStat := FwPreparedStatement():New(cDataQuery)
...
oPrepStat:SetLike(nI, aQryValues[nI, QRY_VAL_VALUE])
...
oPrepStat:SetString(nI, cTemp)
...
cDataQuery := oPrepStat:getFixQuery()
cTempAlias := GetNextAlias()
DbUseArea(.T., "TOPCONN", TcGenQry(,, cDataQuery), cTempAlias, .F., .F.)

Acima a classe FwPreparedStatement é usada para ajudar na construção da consulta SQL, essa classe colabora com a avaliação de instruções maliciosas que vieram pelos query parameters com as chaves que irão tornar-se componentes na consulta.
Uma opção a FwPreparedStatement é a função TcGenQry2.

A outra alteração que serviu de base para a implementação foi a utilização de um mapa entre os campos na tabela e as propriedades retornadas pelo endpoint. O ganho com isso é a facilidade para descobrir o campo que certa propriedade se refere, assim os recursos são implementados de forma mais "simplificada".

// Mapeia os campos da query com as propriedades
aFieldsMap := {;
    {"email", "ZT0_EMAIL", "C", "ZT0_EMAIL"},;
    {"user_id", "ZT0_USRID", "C", "ZT0_USRID"},;
    {"name", "ZT0_NOME", "C", "ZT0_NOME"},;
    {"admin", "ZT0_ADMIN", "L", "ZT0_ADMIN"},;
    {"inserted_at", "ZT0_INS_AT", "D", "I_N_S_D_T_"},;
    {"updated_at", "ZT0_UPD_AT", "D", "S_T_A_M_P_"} ;
}

As propriedades usadas

A lista dos componentes de query parameters utilizados para permitir essas operações é apresentada a seguir.

page
pagesize
order
fields
aQueryString

A paginação

page e pagesize: a combinação que permite receber ?page=1&pagesize=10 e construir um retorno com os primeiros 10 itens da 1a página e também permite a requisição como ?page=11&pagesize=6 em que 11a página será exibida com 6 itens. Isso é relevante demais para páginas web ou aplicativos que no carregamento inicial não precisam de um volume grande de itens para exibição. O conceito de paginação por completo precisa ainda de uma indicação da existência de mais itens e isso é atendido com a contagem.

Os trechos de código destacados para paginação estão a seguir.

wsreceive page, pageSize
...
default self:page := 1
default self:pageSize := 10
...
// montagem da paginação
nItemFrom := (self:page - 1) * self:pageSize + 1
nItemTo := (self:page) * self:pageSize
...
cProjQuery += "ROW_NUMBER() OVER (order by "+ xyz +") SEQITEM "
...
cDataQuery += "where SEQITEM >= "+ cValToChar(nItemFrom) +" and SEQITEM <= "+ cValToChar(nItemTo) +" "

Em resumo, (1) receber os query parameters, (2) garantir valor padrão e então (3) utilizar o recurso ROW_NUMBER() OVER na consulta SQL para a recuperação dos registros e a marcação de sequência que posteriormente já chega filtrada na camada Advpl. Sem necessidade de if ou incrementos no Advpl.

A ordenação

order: a chave que permite indicar qual a ordem que o retorno dos dados deve seguir, receber a instrução ?order=name indica que ordenar pela propriedade name, independente do que esta propriedade signifique internamente no endpoint e receber ?order=-inserted_at,name indica retornar por ordem inversa de criação (sendo os mais recentes primeiro) e ordem alfabética dos nomes.

Os trechos de código a serem destacados sobre ordenação estão a seguir.

wsreceive order
...
default self:order := ""
...
// montagem da ordem
if !Empty(Alltrim(self:order))
        aTemp := StrTokArr(self:order, ",")
        nMax := Len(aTemp)

        cOrderBy := ""
        for nI := 1 to nMax
        // um monte de código para identificar os campos e ordenação
        next nI
        // Remove a última vírgula (,)
        cOrderBy := SubStr(cOrderBy, 1, Len(cOrderBy)-1)
    endif

if Empty(cOrderBy)
    cOrderBy := "ZT0_NOME asc"
endif
...
cProjQuery += "ROW_NUMBER() OVER (order by "+ cOrderBy +") SEQITEM "

Este é o primeiro dos recursos permitidos que exige algoritmo para identificar a lista das propriedades e os campos que precisarão ser utilizados neste ordenação, receber ?order=-age,name significa reconhecer os campos ou expressões associados com estas propriedades e neste caso, usando o mapa mencionado anteriormente. Por último usar esta expressão na consulta SQL e assim garantir a ordenação em conjunto com a marcação e sequenciamento dos registros pela função ROW_NUMBER() OVER(order) nome_da_coluna.

Alguns bancos de dados podem não suportar a ordenação em conjunto com a paginação, vale estudar o banco de dados e versão utilizada para garantir o máximo possível ainda em nível de banco de dados e não na camada Advpl.

A projeção

fields: a chave por onde são indicadas as propriedades que devem ser retornadas do recurso pesquisado, um exemplo é retornar somente email e name quando recebido ?fields=email,name. Isso facilita os inúmeros casos quando poucas informações são exigidas em uma requisição, mas o item possui outras várias propriedades. Esta é mais uma das propriedades que utiliza do mapa de propriedades e campos como referência para sua execução.

Os trechos para destaque da projeção de propriedades da api estão a seguir.

wsreceive fields
...
default self:fields := ""
...
// monta as propriedades escolhidas para retorno
aRetProps := StrTokArr(self:fields, ",")
nRetProps := Len(aRetProps)

if nRetProps == 0
    aRetProps := {"email", "user_id", "name", "admin", "inserted_at", "updated_at"}
    nRetProps := Len(aRetProps)
endif
...
jTempItem := aTail(jResponse["items"])

for nI := 1 to nRetProps
    // recupera o nome da propriedade
    cTemp := aRetProps[nI]

    // recupera o mapa propriedade x campo
    nTemp := aScan(aFieldsMap, {|x| x[MAP_PROP] == cTemp})

    if nTemp > 0
        // recupera o valor para a propriedade
        xPropValue := (cTempAlias)->(FieldGet(FieldPos(aFieldsMap[nTemp, MAP_FIELD])))

        // atribui o valor na propriedade
        if aFieldsMap[nTemp, MAP_TYPE] == "C"
            jTempItem[cTemp] := RTrim(xPropValue)
        elseif aFieldsMap[nTemp, MAP_TYPE] == "L"
            jTempItem[cTemp] := xPropValue == "1"
        else
            jTempItem[cTemp] := xPropValue
        endif
    endif
next nI

Os passos na implementação são (1) recuperar as propriedades indicadas para retorno, (2) transformar em lista usando o mapa, com o cuidado de limitar as propriedades de retorno apropriadas e (3) montar a resposta considerando o recebido na requisição.

A montagem do retorno está longe de ter o código mais apropriado e genérico, contudo dá uma excelente indicação do quão complicado é lidar com tipos e expressões retornadas da tabela para a api.

O filtro

propriedade=valor: este é o recurso que não está associado com uma chave específica. Filtros avançados e com expressões complexas estão associados com o parâmetro ?filter=expressão, contudo a construção de um parser para expressões e complicada demais para ser simplificada e demonstrada nessa série, em função disso o caminho para mostrar filtros de uma forma que funcione minimamente são os filtros como este, ?admin=true onde indica os perfis de administradores, ou ?name=a&admin=true em que montaria uma condição SQL similar à ZT0_NOME like '%a%' and ZT0_ADMIN = '1' e retornaria os perfis com a letra a minúscula no nome e são administradores.

Com os exemplos indicados é possível perceber que usando o mapa de propriedades x campos existe a chance de trocar o tipo de operador conforme o tipo ou nome do campo/propriedade ou qualquer outra lógica, a decisão no código de exemplo foi usar a comparação com o operador like para caracteres, a operação = '1' para a propriedade admin e a operação = para os demais campos. Qualquer comparação com operadores diferentes exigiria a implementação de mais complexidade na montagem da expressão a ser recebida na requisição para o filtro e consequentemente mais complexidade para identificar o que fazer e montar a consulta SQL.

Os trechos importantes para a implementação são apresentados a seguir.

// monta a condição para a query
//  suporta filtros simples com operador LIKE -> campo like %valor%
cCondition := "ZT0.D_E_L_E_T_ = ' ' "
aQryValues := {}
for nI := 1 To Len(self:aQueryString)
    cTempField := Lower(self:aQueryString[nI, QRY_PARAM_KEY])
    nTemp := aScan(aFieldsMap, {|x| x[MAP_PROP] == cTempField})
    // quando encontra cria a expressão e guarda o valor para atribuir
    if nTemp > 0
        if aFieldsMap[nTemp, MAP_TYPE] == "C"
            cCondition += "and ZT0." + aFieldsMap[nTemp, MAP_FIELD] + " like ? "
        else
            cCondition += "and ZT0." + aFieldsMap[nTemp, MAP_FIELD] + " = ? "
        endif
        // mantem par com tipo [QRY_VAL_TYPE] e valor [QRY_VAL_VALUE]
        aAdd(aQryValues, {aFieldsMap[nTemp, MAP_TYPE], self:aQueryString[nI, QRY_PARAM_VALUE]} )
    endif
next nI
...
// tabela e condições
cSubQuery := "from " + RetSqlName("ZT0") + " ZT0 "
cSubQuery += "where " + cCondition
...
// query para os dados
cDataQuery := "select * "
cDataQuery += "from ( " + cProjQuery + cSubQuery + " ) QUERYDATA "
cDataQuery += "where SEQITEM >= "+ cValToChar(nItemFrom) +" and SEQITEM <= "+ cValToChar(nItemTo) +" "

Os passos para realizar o filtro são os mais complexos, envolve (1) percorrer todas as propriedades recebidas por query parameters, (2) identificar os componentes que são propriedades válidas para o filtro (mais uma vez o mapa em ação), (3) verificar qual operador utilizar conforme propriedade e campo na consulta SQL, (4) marcar o valor para ser preenchido com ? pois depois será substituído pelo valor com uso da classe FwPreparedStatement, (4) substituir o valor e finalmente (5) montar e executar a query com a condição interferindo no resultado da paginação (expressão ROW_NUMBER OVER()).
Essa dificuldade é paga quando o retorno da api é minimizado e quando a aplicação cliente não precisa aplicar uma preparação pesada para lidar com os dados!

A contagem

O único dos recursos que não é um pedido do cliente e sim um retorno adicional para a paginação. Sem a indicação da quantidade de registros totais, a aplicação cliente precisaria fazer uma requisição e não ter dado retornado para saber que "acabou" e não há mais dados. Com a indicação da quantidade total com alguma propriedade como total, size, quantity, etc é possível informar ao cliente o número de registros e evitar uma última requisição sem dado para retornar.

Um modelo alternativo é o seguido pelo guia de api da Totvs com o uso da propriedade has_next, com detalhes neste link. O benefício com esta propriedade é indicar de forma simplificada para o cliente a existência de mais registros para a busca, o contra-ponto é não conseguir indicar o total de registros só com ela.

Os detalhes da implementação deste retorno estão a seguir.

// Recupera a quantidade de registros
cCountQuery := "select count(*) ROWS_QT " + cSubQuery
...
oPrepStat := FwPreparedStatement():New(cCountQuery)
for nI := 1 to Len(aQryValues)
// lógica para preencher as marcações com ? da query
next nI

cCountQuery := oPrepStat:getFixQuery()
DbUseArea(.T., "TOPCONN", TcGenQry(,, cCountQuery), cTempAlias, .F., .F.)

if (cTempAlias)->(EOF())
    nCount := 0
else
    nCount := (cTempAlias)->ROWS_QT
endif
jResponse["size"] := nCount

Depois de entender como funciona a consulta SQL para a recuperação dos dados, não há segredo na consulta SQL de fazer a contagem, afinal única alteração que acontece é a substituição da lista de campos da expressão select por count(*).

Conclusão

Esta é a primeira publicação da série que apresenta alta quantidade de código, conceitos e também o uso das propriedades da classe e métodos do rest com Advpl. Tudo isso implica em conteúdo denso para assimilar e entender com profundidade.

O código apresentado tem muito a ser melhorado e pode ser utilizado em uma api em produção com as melhorias apropriadas para casos específicos. Um código similar ao mostrado nesta publicação foi base para a implementação da classe FwAdapterBaseV2, que possui estes conceitos encapsulados e pode ser usada na construção de apis. A próxima publicação será uma terceira versão desse endpoint de listagem usando a classe FwAdapterBaseV2.

O código a seguir mostra a implementação completa de método de listagem, que também pode ser visualizado no pull request no GitHub.

wsmethod GET V2ALL wsreceive page, pageSize, order, fields wsservice Perfis
    local lProcessed    as logical
    local jResponse     as object
    local jTempItem     as object
    local cTempAlias    as character
    local cDataQuery    as character
    local aFieldsMap    as object
    local nItemFrom     as numeric
    local nItemTo       as numeric
    local cOrderBy      as character
    local cOrdDirection as character
    local lDesc         as logical
    local aTemp         as array
    local cTempField    as character
    local nTemp         as numeric
    local nI            as numeric
    local nMax          as numeric
    local cCondition    as character
    local aQryValues    as array
    local oPrepStat     as object
    local aRetProps     as array
    local nRetProps     as numeric
    local xPropValue
    local nCount        as numeric
    local cCountQuery   as character
    local cProjQuery    as character
    local cSubQuery     as character
    lProcessed := .T.

    // Define o tipo de retorno do método
    self:SetContentType("application/json")

    // As propriedades da classe receberão os valores enviados por querystring
    // exemplo: /rest/microblog/v1/perfis?page=1&pageSize=5&order=-name&fields=name,email
    default self:page := 1
    default self:pageSize := 10
    default self:order := ""
    default self:fields := ""
    // Mapeia os campos da query com as propriedades
    aFieldsMap := {;
        {"email", "ZT0_EMAIL", "C", "ZT0_EMAIL"},;
        {"user_id", "ZT0_USRID", "C", "ZT0_USRID"},;
        {"name", "ZT0_NOME", "C", "ZT0_NOME"},;
        {"admin", "ZT0_ADMIN", "L", "ZT0_ADMIN"},;
        {"inserted_at", "ZT0_INS_AT", "D", "I_N_S_D_T_"},;
        {"updated_at", "ZT0_UPD_AT", "D", "S_T_A_M_P_"} ;
    }
    // montagem da paginação
    nItemFrom := (self:page - 1) * self:pageSize + 1
    nItemTo := (self:page) * self:pageSize

    // montagem da ordem
    if !Empty(Alltrim(self:order))
        aTemp := StrTokArr(self:order, ",")
        nMax := Len(aTemp)

        cOrderBy := ""
        for nI := 1 to nMax

            lDesc := (SubStr(aTemp[nI], 1, 1) == "-")
            if lDesc
                cTempField := SubStr(aTemp[nI], 2)
                cOrdDirection := " desc"
            else
                cTempField := aTemp[nI]
                cOrdDirection := " asc"
            endif

            nTemp := aScan(aFieldsMap, {|x| x[MAP_PROP] == cTempField})
            if nTemp > 0
                cOrderBy += aFieldsMap[nTemp, MAP_INTERNAL_FIELD] + cOrdDirection + ","
            endif
        next nI
        // Remove a última vírgula (,)
        cOrderBy := SubStr(cOrderBy, 1, Len(cOrderBy)-1)
    endif

    if Empty(cOrderBy)
        cOrderBy := "ZT0_NOME asc"
    endif

    // monta a condição para a query
    //  suporta filtros simples com operador LIKE -> campo like %valor%
    cCondition := "ZT0.D_E_L_E_T_ = ' ' "
    aQryValues := {}
    for nI := 1 To Len(self:aQueryString)
        cTempField := Lower(self:aQueryString[nI, QRY_PARAM_KEY])
        nTemp := aScan(aFieldsMap, {|x| x[MAP_PROP] == cTempField})
        // quando encontra cria a expressão e guarda o valor para atribuir
        if nTemp > 0
            if aFieldsMap[nTemp, MAP_TYPE] == "C"
                cCondition += "and ZT0." + aFieldsMap[nTemp, MAP_FIELD] + " like ? "
            else
                cCondition += "and ZT0." + aFieldsMap[nTemp, MAP_FIELD] + " = ? "
            endif
            // mantem par com tipo [QRY_VAL_TYPE] e valor [QRY_VAL_VALUE]
            aAdd(aQryValues, {aFieldsMap[nTemp, MAP_TYPE], self:aQueryString[nI, QRY_PARAM_VALUE]} )
        endif
    next nI

    // campos mapeados
    cProjQuery := "select ZT0_EMAIL, ZT0_USRID, ZT0_NOME, ZT0_ADMIN,"
    cProjQuery += "convert(varchar(23), I_N_S_D_T_, 21) ZT0_INS_AT,"
    cProjQuery += "convert(varchar(23), S_T_A_M_P_, 21) ZT0_UPD_AT,"
    cProjQuery += "ROW_NUMBER() OVER (order by "+ cOrderBy +") SEQITEM "

    // tabela e condições
    cSubQuery := "from " + RetSqlName("ZT0") + " ZT0 "
    cSubQuery += "where " + cCondition

    // query para os dados
    cDataQuery := "select * "
    cDataQuery += "from ( " + cProjQuery + cSubQuery + " ) QUERYDATA "
    cDataQuery += "where SEQITEM >= "+ cValToChar(nItemFrom) +" and SEQITEM <= "+ cValToChar(nItemTo) +" "

    oPrepStat := FwPreparedStatement():New(cDataQuery)
    for nI := 1 to Len(aQryValues)
        // atribui os valores de string com operador like
        if aQryValues[nI, QRY_VAL_TYPE] == "C"
            oPrepStat:SetLike(nI, aQryValues[nI, QRY_VAL_VALUE])

        // propriedade admin está com tipo lógico então faz igualdade 1=sim;2=não
        elseif aQryValues[nI, QRY_VAL_TYPE] == "L"
            if (Alltrim(aQryValues[nI, QRY_VAL_VALUE]) == "1" .Or. Alltrim(aQryValues[nI, QRY_VAL_VALUE]) == "true")
                cTemp := "1"
            else
                cTemp := "2"
            endif
            oPrepStat:SetString(nI, cTemp)
        endif
    next nI

    cDataQuery := oPrepStat:getFixQuery()

    cTempAlias := GetNextAlias()
    DbUseArea(.T., "TOPCONN", TcGenQry(,, cDataQuery), cTempAlias, .F., .F.)

    jResponse := JsonObject():New()
    jResponse["items"] := {}

    // monta as propriedades escolhidas para retorno
    aRetProps := StrTokArr(self:fields, ",")
    nRetProps := Len(aRetProps)

    if nRetProps == 0
        aRetProps := {"email", "user_id", "name", "admin", "inserted_at", "updated_at"}
        nRetProps := Len(aRetProps)
    endif

    while (cTempAlias)->(!EOF())
        aAdd(jResponse["items"], JsonObject():New())
        jTempItem := aTail(jResponse["items"])

        for nI := 1 to nRetProps
            // recupera o nome da propriedade
            cTemp := aRetProps[nI]

            // recupera o mapa propriedade x campo
            nTemp := aScan(aFieldsMap, {|x| x[MAP_PROP] == cTemp})

            if nTemp > 0
                // recupera o valor para a propriedade
                xPropValue := (cTempAlias)->(FieldGet(FieldPos(aFieldsMap[nTemp, MAP_FIELD])))

                // atribui o valor na propriedade
                if aFieldsMap[nTemp, MAP_TYPE] == "C"
                    jTempItem[cTemp] := RTrim(xPropValue)
                elseif aFieldsMap[nTemp, MAP_TYPE] == "L"
                    jTempItem[cTemp] := xPropValue == "1"
                else
                    jTempItem[cTemp] := xPropValue
                endif
            endif
        next nI
        (cTempAlias)->(DbSkip())
    enddo

    (cTempAlias)->(DbCloseArea())

    // Recupera a quantidade de registros
    cCountQuery := "select count(*) ROWS_QT " + cSubQuery

    oPrepStat := FwPreparedStatement():New(cCountQuery)
    for nI := 1 to Len(aQryValues)
        // atribui os valores de string com operador like
        if aQryValues[nI, QRY_VAL_TYPE] == "C"
            oPrepStat:SetLike(nI, aQryValues[nI, QRY_VAL_VALUE])

        // propriedade admin está com tipo lógico então faz igualdade 1=sim;2=não
        elseif aQryValues[nI, QRY_VAL_TYPE] == "L"
            if (Alltrim(aQryValues[nI, QRY_VAL_VALUE]) == "1" .Or. Alltrim(aQryValues[nI, QRY_VAL_VALUE]) == "true")
                cTemp := "1"
            else
                cTemp := "2"
            endif
            oPrepStat:SetString(nI, cTemp)
        endif
    next nI

    cCountQuery := oPrepStat:getFixQuery()
    DbUseArea(.T., "TOPCONN", TcGenQry(,, cCountQuery), cTempAlias, .F., .F.)

    if (cTempAlias)->(EOF())
        nCount := 0
    else
        nCount := (cTempAlias)->ROWS_QT
    endif
    jResponse["size"] := nCount

    self:SetResponse(jResponse:ToJson())
return lProcessed

Um microblog usando Protheus - Rest Server, parte 4, classe para rest + modelos MVC

Josimar Junior — Mon, 07 Dec 2020 00:41:55 +0000

Introdução

Nesta parte da série de publicações será abordado como construir o conjunto de operações para incluir, buscar, atualizar e excluir um item utilizando um modelo de dados MVC para as operações que envolvem o banco de dados.
Para essa demonstração o modelo de dados utilizado é o construído na parte anterior, onde foi demonstrado como fazer a publicação de um modelo MVC no Rest e utilizada as URLs padrões /fwmodel/{modelo}/{pk} para realizar as requisições rest. Portanto, em caso de dúvida da implementação do modelo usando nas operações a seguir consulte o código advpl no link.

Por que esta implementação?

A implementação demonstrada a seguir não muda muito da demonstrada na segunda parte desta série, contudo a diferença que existe já proporciona um isolamento de responsabilidades melhor e para algumas situações específicas é uma implementação boa o bastante.
O principal ganho desta implementação comparado com a demonstrada na segunda parte está no fato de que as validações e a gravação dos registros quando inclusão, alteração e exclusão não ficam na mesma função da api/requisição e sim em uma camada interna que pode evoluir de forma independente. Essa independência é relevante para a evolução dos serviços e contextos de negócios envolvidos na api.
Existem várias abordagens com o propósito de separar essas camadas de responsabilidade, mas este não será o momento de explorar qualquer um destes modelos com Advpl e Protheus, isso será feito mais adiante na série. Para as pessoas que possuirem interesse em pesquisar neste momento, alguns dos temas e termos eles são N Layers, Hexagonal Architecture, Clean Architecture, Actors Model e a Orientação a Objetos no design de aplicações, estes são os que lembro no momento.

O efeito do modelo de dados no Protheus!

Um dos principais recursos que o MVC Advpl oferece é a possibilidade de utilizar um determinado contexto de negócio em outros processos ou entidades, seja este primeiro modelo uma entidade ou um processo. Com isso é possível por exemplo na operação de criação de um registro na tabela A, também inserir um registro na tabela B ou qualquer outra entidade que estenda informações do registro na tabela A e tudo isso sem ferir regras de integridade e validações de negócio envolvidos em cada uma dessas tabelas.
Isso é conseguido com o comando FwLoadModel("arquivo") que recupera a definição do modelo de dados dentro da static function ModelDef() e depois disso permite indicar a operação e os dados para criar, recuperar, atualizar ou excluir os registros.
Esta possibilidade de reuso das regras é o que inibe a replicação de diversas validações, inclusive eventuais regras que não estão no dicionário de campos/SX3, e como vantagem adicional a gravação dos dados no modelo pode ser específica deste modelo e isso também será reutilizado.
O único aspecto que acaba não sendo atendido com o uso do modelo MVC combinado com a classe Rest é a listagem dos registros. Isso por que quando utilizado através de tela no Smartclient dentro do Protheus a responsabilidade de listar os itens é do browse e por isso não há implementação no MVC que exiba uma lista por padrão. Em função disso os métodos apresentados a seguir são para operações em um item, um único registro.
Para as pessoas que não entenderam e se perguntaram como a publicação do modelo padrão lida com isso e se perguntaram "Como a /fwmodel/ faz a listagem?" leia o modo avançado da parte anterior nesta documentação e veja a implementação base da classe FwRestModelObject.

Construindo a v2 para api de Perfis

Será apresentada a versão 2 da api para Perfis do microblog e os aspectos que mudaram da v1 para a v2 que serão destacados.
Os comandos relacionados à classe rest Advpl já mencionados não serão explicados novamente, caso tenha dúvida nestes pontos pode consulta a segunda parte da série.

POST /microblog/v2/perfis/

A operação de inclusão na v1 utilizava Reclock e MsUnlock e só validava a existência dos conteúdos que vieram no body da requisição e esse tipo de validação é insuficiente para 99% dos casos.
Isso se tornou os seguintes comandos:

oModel:SetOperation(MODEL_OPERATION_INSERT)

lProcessed := oModel:Activate()
oZT0Header := oModel:GetModel("ZT0_FIELDS")

lProcessed := lProcessed .And. oZT0Header:SetValue("ZT0_EMAIL" , jBody["email"])
lProcessed := lProcessed .And. oZT0Header:SetValue("ZT0_USRID" , jBody["user_id"])
lProcessed := lProcessed .And. oZT0Header:SetValue("ZT0_NOME"  , jBody["name"])

lProcessed := lProcessed .And. oModel:VldData() .And. oModel:CommitData()

O número de linhas aumentou e o código pode ter ficado mais complicado, mas os benefícios já mencionados são garantidos com estas linhas.

:SetValue("ZT0_EMAIL" , jBody["email"]) => quando adicionada uma validação para o campo de email ela passará a ser aplicada aqui.
oModel:VldData() .And. oModel:CommitData() => quando alterada a validação geral do modelo ou como a gravação acontece elas também estarão disponíveis aqui.

GET /microblog/v2/perfis/{perfilId}

A recuperação de um registro usando o modelo MVC acontece da seguinte forma.

lProcessed := (!(Alltrim(self:perfilId) == "") .And. ZT0->(DbSeek(xFilial("ZT0")+self:perfilId)))
oModel:SetOperation(MODEL_OPERATION_VIEW)

lProcessed := oModel:Activate()

if lProcessed
    oZT0Header := oModel:GetModel("ZT0_FIELDS")

    jResponse["email"]   := oZT0Header:GetValue("ZT0_EMAIL")

oModel:Activate() => comando que baseado no registro posicionado na tabela realiza a carga dos dados.
:GetValue("ZT0_EMAIL") => como a informação do campo é recuperada e redirecionada para a resposta. No caso da api para perfis quase não há vantagem entre o DbSeek e a leitura direto do registro na tabela (ZT0->ZT0_EMAIL) para o modelo, pois é um único registro. Isso muda de situação quando o cenário da api é por exemplo para publicações e comentários de uma publicação, como é exigido carregar elementos associados (a lista de comentários de uma publicação ou à qual publicação um comentário pertence), simplesmente posicionar nas tabelas não resolve, o uso do modelo ganha vantagem pois essa lógica e o eventual relacionamento usado estão na definição do modelo e só são usados pelo serviço da api com o modelo MVC instanciado.

PUT /microblog/v2/perfis/{perfilId}

A alteração e atualização dos campos acontece já utilizando os comandos mencionados nas operações de POSTe GET e não há nenhum comando ou método novo do modelo MVC.
O que muda é a operação definida antes do Activate do modelo.
Então a seguir as principais linhas em Advpl na classe do Rest para suportar a operação PUT.

lProcessed := (!(Alltrim(self:perfilId) == "") .And. ZT0->(DbSeek(xFilial("ZT0")+self:perfilId)))
...
oModel:SetOperation(MODEL_OPERATION_UPDATE)
lProcessed := oModel:Activate()
lProcessed := lProcessed .And. oZT0Header:SetValue("ZT0_NOME"  , jBody["name"])
lProcessed := lProcessed .And. oModel:VldData() .And. oModel:CommitData()

DELETE /microblog/v2/perfis/{perfilId}

Assim como na operação PUT nada novo é adicionado nos comandos do modelo, somente o tipo de operação indicada no método Activate. Os principais comandos em Advpl que suportam o DELETE na classe Rest estão a seguir.

lDelete := ZT0->(DbSeek(xFilial("ZT0")+self:perfilId))
oModel:SetOperation(MODEL_OPERATION_DELETE)
lProcessed := oModel:Activate()
lProcessed := lProcessed .And. oModel:VldData() .And. oModel:CommitData()

Conclusão

O código mudou o resultado api e classe? não. Os formatos de entrada e resposta continuaram os mesmos.
Os ganhos de usar o modelo é não repetir validações e principalmente não fazer acesso direto às tabelas para recuperar conteúdo. É uma versão ideal para um serviço rest? Bem, não exatamente. Existem tópicos a serem melhorados e o principal é ter uma abstração receba os dados da api e só se comunique com o modelo e a resposta dessa abstração vai depois para o método que atendeu à requisição, algo a ser abordado numa das publicações futuras.
É possível conferir o código feito exclusivamente para publicação neste link.
A próxima etapa será implementar recursos como paginação e ordem na recuperação de lista dos itens GET geral.

Um microblog usando Protheus - Rest Server, parte 3, serviço padrão rest de modelos mvc

Josimar Junior — Thu, 03 Dec 2020 00:53:49 +0000

Introdução

Nesta parte será apresentado o serviço de rest padrão que é oferecido quando utilizado MVC.
Para um bom entendimento de como funciona é importante que a pessoa esteja familiarizada com a construção de modelos de dados para MVC.
O conteúdo disponível oficialmente sobre MVC está no link.

Essa parte é continuação da anterior e portanto caso tenha chegado até aqui sem ler a parte anterior, sugiro olhar ao menos a estrutura da tabela ZT0 - Perfis.
Segunda parte

A construção do modelo de dados

O modelo de dados para este caso é bem simples, como a tabela possui poucos campos e ainda não foi adicionada validação alguma, somente recuperar a estrutura e definir os ids para os componentes é exigido.

O ModelDdef ficou assim:

static function ModelDef()
    local oModel   as object
    local oStrZT0  as object

    oStrZT0 := FWFormStruct(1, "ZT0")
    oModel := MpFormModel():New("ZMBMODEL")

    oModel:AddFields("ZT0_FIELDS", , oStrZT0)
    oModel:SetDescription("Cadastro de perfis")
    oModel:GetModel("ZT0_FIELDS"):SetDescription("Perfis")
return oModel

Os detalhes importantes neste modelo são:

as descrições para o modelo completo e para o cabeçalho/enchoice;
o id como ZMBMODEL, este id define qual o nome da função de usuário para os ponto de entradas que este modelo vai invocar e portanto, colocar com o mesmo nome do fonte faria acontecer alguns comportamentos inusitados (menu não aparecer, programa travar, erro durante carga, etc). Com o que foi definido nesse modelo os ponto de entradas serão encontrados pela função U_ZMBMODEL.

Só com a definição do modelo não acontece a publicação do serviço rest do MVC, para isso é necessário adicionar os comandos PUBLISH USER MODEL ou PUBLISH MODEL, respectivamente para funções de usuário e funções do padrão.

A documentação sobre os recursos oferecidos quando estes comandos são adicionados a fontes compilados estão descritos nessas documentações.
Publicando um modelo como rest
FwRestModel

Nesta publicação não será explicado o modelo mais avançado indicado pela segundo documentação, contudo serão explicadas as possibilidades criadas com esta forma avançada.
Dica: modelos que possuem "condições" para a montagem de sua estrutura têm grandes chances de sofrer com comportamentos inadequados e erros, pois as threads para resposta dos serviços de rest raramente têm as mesmas variáveis públicas preenchidas quando comparadas com a execução por tela/smartclient, por isso evite condições na montagem do seu modelo de dados.

Fazendo a publicação de um modelo

Para o modelo MVC do cadastro de Perfis foi realizada duas publicações de serviços: uma com o id perfis e outra com o id ZMBA010.
Os comandos que fizeram estas publicações foram:

// http://localhost:18085/rest/fwmodel/Perfis/
PUBLISH USER MODEL REST NAME Perfis SOURCE ZMBA010

// http://localhost:18085/rest/fwmodel/ZMBA010/
PUBLISH USER MODEL REST NAME ZMBA010 SOURCE ZMBA010

Após a compilação do arquivo com estas instruções e o ambiente configurado para atender a requisições REST, fica disponível na URI .../fwmodel/ZMBA010/{chave} a recuperação de dados e informações sobre o cadastro MVC.
Essa URI é a padrão para qualquer programa, portanto qualquer programa que teve seu modelo publicado ficará acessível a partir da URI /fwmodel/{programa}/{chave}.

Explorando o modelo exposto

Três endpoints são disponibilizados para permitir a leitura e análise de informações sobre o modelo publicado.

/schema - retorna a documentação da estrutura dos campos que inclui o nome, o tipo, o tamanho, etc. Traz bastante informação sobre o modelo de dados.
/xmldata - retorna a estrutura de um item para ser utilizado posteriormente nas operações de POST e PUT.

<?xml version="1.0" encoding="UTF-8"?>
<ZMBMODEL Operation="1" version="1.01">
    <ZT0_FIELDS modeltype="FIELDS">
        <ZT0_FILIAL order="1">
            <value></value>
        </ZT0_FILIAL>
        <ZT0_USRID order="2">
            <value></value>
        </ZT0_USRID>
        <ZT0_EMAIL order="3">
            <value></value>
        </ZT0_EMAIL>
        <ZT0_NOME order="4">
            <value></value>
        </ZT0_NOME>
    </ZT0_FIELDS>
</ZMBMODEL>

/xmldatadetail - retorna a estrutura de um item (como o anterior) e com detalhes adicionais como tamanho, tipo do dado, título e obrigatoriedade.

<?xml version="1.0" encoding="UTF-8"?>
<ZMBMODEL Operation="1" version="1.01">
    <ZT0_FIELDS modeltype="FIELDS">
        <ZT0_FILIAL order="1" len="2,0" datatype="C" info="Filial" >
            <value></value>
        </ZT0_FILIAL>
        <ZT0_USRID order="2" len="6,0" datatype="C" info="cod usuário" obrigat="1" >
            <value></value>
        </ZT0_USRID>
        <ZT0_EMAIL order="3" len="100,0" datatype="C" info="email" obrigat="1" >
            <value></value>
        </ZT0_EMAIL>
        <ZT0_NOME order="4" len="100,0" datatype="C" info="nome" obrigat="1" >
            <value></value>
        </ZT0_NOME>
    </ZT0_FIELDS>
</ZMBMODEL>

Estes endpoints somente retornam no formato application/xml.

Recuperando dados usando o modelo

Os métodos e operações permitidos estão na tabela a seguir.

método	path	objetivo	usa informação do...
POST	`/fwmodel/Perfis/`	incluir um registro	body
GET	`/fwmodel/Perfis/`	incluir um registro	parâmetros de query
GET	`/fwmodel/Perfis/{pk}`	incluir um registro	parâmetros de query
PUT	`/fwmodel/Perfis/{pk}`	incluir um registro	body
DELETE	`/fwmodel/Perfis/{pk}`	incluir um registro	nenhum

Estas são exatamente as mesmas operações que foram feitas na parte anterior, contudo não foi feita a criação de uma classe Rest para responder a estas requisições e sim utilizado um modelo mvc para lidar com o cadastro na sua forma padrão.

Estes endpoints e métodos respondem por padrão como Content-Type: application/json, sendo possível também receber no formato application/xml e para isso faça a requisição informando no header a chave Accept: application/xml; charset=utf-8.

Os exemplos de como usar os endpoints estão na coleção do postman no repositório.

Detalhes da api

A principal diferença para o serviço construído antes são as novas possibilidades que a publicação do padrão permite.

Na listagem dos itens é possível utilizar parâmetros de query que otimizam a busca permitindo recuperar somente os campos desejados e também controlar a paginação do itens.

paginação: combinando as propriedades count e startindex é possível fazer a paginação, um exemplo é a expressão /fwmodel/zmba010?count=20&startindex=2 que traria os registros de 21 a 40 conforme a ordem usada no modelo (normalmente a ordem de índice 1).
filtragem: com a propriedade filter é possível determinar uma expressão que irá restringir o resultado, como filter=ZT0_ADMIN = 1.
restrição de campos: com a propriedade fields é possível reduzir a quantidade de campos retornados, de forma a otimizar o tempo de resposta e ocupação de banda na rede, a expressão fields=ZT0_USRID,ZT0_NOME faria retornar somente os campos ZT0_USRID e ZT0_NOME.

Ter estas funcionalidades somente com a construção do modelo de dados MVC é um ganho imenso e portanto, no advento de não ter muito tempo para desenvolver uma api ou não querer deixar a api muito simples (como a da parte anterior), publicar um modelo é uma excelente saída. A desvantagem está no fato dos nomes dos campos serem as propriedades e com isso obrigar os clientes das apis lidarem com coisas que podem não fazer sentido nenhum para a aplicação cliente.

O modelo avançado

Nessa documentação já citada existe um recurso não utilizado na publicação do modelo para Perfis.
A opção RESOURCE OBJECT <objeto> permite determinar qual a classe fará uma parte da interpretação dos comandos entre o modelo (que possui os dados) e o fwmodel (que responde à requisição).
Tendo o controle dessa camada intermediária é possível implementar mais parâmetros de query e estender comportamentos, como permitir a definição de ordem dos dados na listagem geral que não é permitida por padrão.
Na documentação tem o fonte FWRestModelObject.prx com uma implementação bem similar a do padrão e um exemplo com a implementação simulada para um serviço de filiais.

Conclusão

Este é um tópico em que é importante utilizar a coleção do postman e os endpoints para ver as coisas acontecerem no sistema.
Muito é oferecido somente com a publicação do modelo e cadastros simples são bem atendidas somente com isso.
Não será feito uso deste formato de api no microblog usando o Protheus e este formato foi demonstrado aqui para deixar explícita uma das possibilidades.
A próxima publicação será sobre usar o modelo MVC para lidar com as operações de Criação, Atualização, Exclusão e Leitura no banco de dados ao invés de fazer estas operações diretamente com Reclock ou Insert.

Um microblog usando Protheus - Rest Server, parte 2, classe para serviço básico

Josimar Junior — Sun, 29 Nov 2020 23:06:20 +0000

Introdução

Na primeira parte foi dito sobre o que seria construído e o que seria abordado e explicado nessa série de publicações.
Essa será a primeira publicação que conterá código e informações sobre a configuração do ambiente e o modus operandi para a construção do microblog.
Para o melhor aproveitamento nesta publicação é esperado a pessoa lendo tenha uma compreensão razoável de como o Protheus funciona com relação aos dicionários e tabelas/aliases, assim como entendimento intermediário sobre linguagem de programação Advpl.
Algumas definições e conceitos podem ter links de documentação e espero conseguir prover o máximo dessas referências para ajudar.

Ambiente

O ambiente é o Protheus release 12.1.27 expedido em Outubro com os binários DbAccess, Appserver e Smarclient e a lib também expedidos junto com essa release. Portanto para replicar o ambiente de desenvolvimento pode-se iniciar uma base e seguir os passos com os recursos utilizados e mencionados no decorrer das publicações ou utilizar o arquivo de backup mencionado no repositório do Github com a construção do microblog.

Estrutura de tabelas

Para a construção dos recursos do microblog foram criadas três tabelas:

ZT0: conterá informações relacionadas com os perfis;
ZT1: conterá informações sobre as publicações e comentários e;
ZT2: conterá informações sobre os perfis que seguem uns aos outros. Os dicionários de tabelas (SX2), índices (SIX) e campos (SX3) estão disponíveis na forma de arquivos .dtc no repositório do microblog para a consulta e réplica da configuração das tabelas, contudo não há segredo e um diagrama simplificado dos relacionamentos é exibido a seguir. Com o diagrama é possível perceber que poucas regras serão aplicadas contudo, é seguro dizer que serão regras e validações o suficiente para entender onde melhor aplicá-las quando respondendo à requisições por api. O diagrama simplificado mostra os relacionamentos da tabela de Perfis (ZT0) com as Publicações (ZT1) e com a tabela que guardará os Perfis seguidores e seguidos (ZT2). O principal campo utilizado para relacionamento nessas tabelas é o ZT0_USRID, este será o id de um usuário do Protheus, sim um usuário do sistema. O principal motivo para utilizar um usuário do sistema é conseguir com a combinação de email (ou id) e senha realizar a autenticação no sistema (login no Protheus). Além deste campo como chave, a tabela de Publicações tem o próprio campo chave ZT1_ID que terá um valor aleatório sendo gerado e conferido para não existir conflitos na base e a última tabela tem um chave composta por id de usuário seguidor e id de usuário seguido. Essa é a estrutura de tabelas que conterá as principais operações e apoiará a construção do microblog.

Configuração do servidoe de Rest Protheus

Os detalhes de configuração podem ser conseguidos em um dos links mencionados no tópico anterior, que é esta documentação aqui.
As seções que vou destacar a importância são:
[HTTPREST]: aqui é determinado qual ips/dns o Appserver irá ouvir e aguardar pelas requisições.
Nesta série de publicações é utilizada a seguinte configuração:

; REST CONFIG
[HTTPV11]
ENABLE=1
SOCKETS=HTTPREST
; ADVPL=1

SOCKETS=HTTPREST => determina qual a seção seguinte para as demais configurações que neste caso será a seção [HTTPREST];
ADVPL=1 => determina qual modelo de accept de requisições será utilizado 1 é o Advpl e 0 é o misto de TLPP com binário. Neste caso a chave está comentada e portanto deixará o que produto decidir usar, que por enquanto é o modelo Advpl. Mais detalhes dessa configuração veja este artigo.

[HTTPREST]
PORT=18085
URIS=URI
SECURITY=1

Na configuração para o microblog foi definida a porta como 18085 (com a chave PORT=18085) e habilitada a segurança no servidor Rest (com a chave SECURITY=1), com isso as requisições por padrão estão "seguras" e exigem que seja provido algum tipo de autenticação para que a resposta aconteça.
A chave URIS=URI define qual URLs vão ser estabelecidas como path raíz para a montagem das URLs/paths dos métodos.

[URI]
URL=/rest
PREPAREIN=99,01
INSTANCES=1,2,1,1
CORSENABLE=1
ALLOWORIGIN=*
ENVIRONMENT=p12microblog

Essa é a seção que possui a maior quantidade de configurações e onde boa parte dos problemas de configuração surgem, portanto item a item será explicado.

URL=/rest => indica o começo da URL que o servidor irá aguarda e responder às requisições. Pode ser configurado com / e portanto logo após a raiz será o path para o método/classe. Aqui foi configurado como /rest pelo hábito. Este é o endereço que a página com a lista de serviços é exibida e pode ser consultada.
PREPAREIN=99,01 => determina o grupo de empresa e filial que as threads para resposta terão o ambiente preparado. Caso a empresa seja diferente de 99 garanta que tenha licenças o suficiente para a preparação destes ambientes. É possível também definir como ALL contudo isso traz uma necessidade das requisições começarem a incluir o header tenantid: 99,01 para que seja possível determinar qual o grupo e filial responsável por responder a requisição, quando acontece de ter a configuração como ALL e não é informado o tenantid na requisição, qualquer thread poderá responder e com isso a primeira thread livre é que fará a resposta. Em situações de negócio, quando filial já é determinante para encontrar registros, ter a resposta acontecendo ao "acaso" considerando grupo e filial, definitivamente não é um risco que vale correr.
INSTANCES=1,2,1,1 => aqui são indicados o limite inferior e superior de threads para responder às requisições. Os últimos dois parâmetros indicam a quantidade para tentar deixar livre e quantidade para incrementar quando necessário. Um exemplo onde é possível explicar melhor é 10,50,2,5 que significa suba imediatamente 10 threads, pode subir até 50 threads, tente deixar 2 threads livres e quando não conseguir prepare 5 novas threads.
CORSENABLE=1 => essa é a configuração que permite aplicações clientes do rest server exibir conteúdo respondido pelo Rest Advpl nos navegadores. Essa chave é essencial para aplicações Angular, React ou Vuejs que façam requisições ao servidor Protheus.
ALLOWORIGIN=* => configuração adicional à chave CORSENABLE aqui são indicados quais os hosts (ip ou dns do servidores) podem exibir o conteúdo respondido. O valor * determina que pode ser exibido por qualquer endereço, contudo uma configuração útil de exemplo é ALLOWORIGIN=meuapp.company.com,appxyz.serverabc.com.br.
ENVIRONMENT=p12microblog => chave que indica qual o ambiente terá as threads preparadas. Este é outro elemento comum de problemas na configuração, pois eventuais problemas no ambiente indicado aqui (como acessos de usuários, limitação de licenças e uso simultâneo por Smartclient) afetarão a execução dos métodos e classes rest no Protheus. A imagem a seguir mostra como verificar se a configuração inicial está correta.

Escrevendo os serviços

Este é o primeiro serviço sendo escrito e portanto terá a maior quantidade de detalhes oferecidos, os demais irão se basear na explicação contida nos próximos parágrafos.
Os arquivos de header exigidos para a compilação do arquivo .prw com a classe para o serviço rest são:

#include "protheus.ch"
#include "restful.ch"

Definição da classe

A indicação do nome da classe Perfis e qual a descrição para exibição na página de serviços.

wsrestful Perfis description "Trata a atualização dos perfis que usam o microblog"
.
.
.
end wsrestful

A definição das propriedades na classe Perfil que serão preenchidas e podem ser utilizadas para a montagem da resposta. Essas propriedades serão preenchidas quando vierem elementos com o mesmo nome como parâmetros de path e query ou no header da requisição, os listados a seguir serão exemplos nos parâmetros de path e query.

    wsdata pageSize         as integer optional
    wsdata page             as integer optional
    wsdata perfilId         as character optional

Na construção acima as propriedades são opcionais e portanto caso não estejam presentes a execução não é interrompida ainda na camada de framework. É importante definir o tipo de dado para que não seja exigido a checagem ou conversão na camada de resposta, os tipos disponíveis são .
As definições dos métodos que irão responder para a URL host:port/rest/microblog/v1/perfis quando GET ou POST acontece da seguinte forma:

    wsmethod GET V1ALL description "Recupera todos os perfis" wssyntax "/microblog/v1/perfis" path "/microblog/v1/perfis"
    wsmethod POST V1ROOT description "Cria um perfil para o microblog" wssyntax "/microblog/v1/perfis" path "/microblog/v1/perfis"

Os valores GET V1ALL e POST V1ROOT associados com wsmethod são as identificações dos métodos construídos para responder a requisição. A marcação wssyntax estabelece a URI que ficará visível na página de serviços e a marcação path estabelece o endereço de URI que o método responderá.
Os métodos de HTTP fazem parte da identificação do método e portanto não é possível fazer um http POST ser respondido pelo método GET XYZ.
As definições dos métodos que irão responder para a URL host:port/rest/microblog/v1/perfis/{perfilId} quando GET, PUT ou DELETE são:

    wsmethod GET V1ID description "Recupera um perfil pelo id" wssyntax "/microblog/v1/perfis/{perfilId}" path "/microblog/v1/perfis/{perfilId}"
    wsmethod PUT V1ID description "Faz a atualização de um perfil" wssyntax "/microblog/v1/perfis/{perfilId}" path "/microblog/v1/perfis/{perfilId}"
    wsmethod DELETE V1 description "Faz a exclusão de um perfil" wssyntax "/microblog/v1/perfis/{perfilId}" path "/microblog/v1/perfis/{perfilId}"

O quê há de diferente com os primeiros métodos? A identificação dos verbos http e a inclusão da expressão /{perfilId} nos paths e isso define limites e comportamentos importantes. A primeira coisa é que esta expressão faz com que uma requisição como GET /rest/microblog/v1/perfis/xxx001 seja respondida pelo método GET V1ID e não pelo método GET V1ALL. A segunda é que o valor da propriedade perfilId será xxx001.
Estas são as definições dos métodos e URIs que serão respondidas por esta classe.
As boas práticas envolvidas até aqui foram:

definir versionamento no path/uri: é um formato que possui contestações, contudo é mais simples de perceber qual o serviço/método/classe/assinatura devem ser utilizados.
incluir o nome da classe no path: neste exemplo a classe é Perfis e faz parte da combinação de agrupador de path escolhido microblog/v1/perfis. ## Definição dos métodos A seguir a implementação dos métodos são mostradas e os comandos relacionados com o rest são explicados.

POST - inclui um item

wsmethod POST V1ROOT wsservice Perfis
    local lProcessed as logical
    local jBody      as object
    local jResponse  as object

    lProcessed := .T.
    self:SetContentType("application/json")

    jBody := JsonObject():New()
    jBody:FromJson(self:GetContent())

    jResponse := JsonObject():New()

    if (jBody["email"] == Nil .Or. jBody["user_id"] == Nil .Or. jBody["name"] == Nil)
        jResponse["error"] := "body_invalido"
        jResponse["description"] := "Forneça as propriedades 'email', 'user_id' e 'name' no body"

        self:SetResponse(jResponse:ToJson())
        SetRestFault(400, jResponse:ToJson(), , 400)
        lProcessed := .F.
    else
        DBSelectArea("ZT0")
        Reclock("ZT0", .T.)
            ZT0->ZT0_FILIAL := xFilial("ZT0")
            ZT0->ZT0_EMAIL  := jBody["email"]
            ZT0->ZT0_USRID  := jBody["user_id"]
            ZT0->ZT0_NOME   := jBody["name"]
        ZT0->(MsUnlock())

        jResponse["email"]   := ZT0->ZT0_EMAIL
        jResponse["user_id"] := ZT0->ZT0_USRID
        jResponse["name"]    := ZT0->ZT0_NOME
        // jResponse["inserted_at"] := ZT0->S_T_A_M_P_
        // jResponse["updated_at"] := ZT0->I_N_S_D_T_

        self:SetResponse(jResponse:ToJson())
    endif

return lProcessed

Neste método o objetivo é recuperar o conteúdo enviado no body pela requisição e criar um registro na tabela quando o conteúdo é válido. Os trechos relacionados com rest em Advpl são:
wsmethod POST V1ROOT wsservice Perfis => indicação do corpo do método definido anteriormente na classe.
self:SetContentType("application/json") => define que a resposta terá o conteúdo como application/json.
jBody:FromJson(self:GetContent()) => preenche a variável jBody com o conteúdo recebido no body da requisição.
if (jBody["email"] == Nil .Or. jBody["user_id"] == Nil .Or. jBody["name"] == Nil) => forma com que os conteúdos das propriedades no body estão sendo validados, quando alguma destes valores não foi informado é considerada uma requisição inválida.
self:SetResponse(jResponse:ToJson()) => definição da resposta quando percebido erro no body.
SetRestFault(400, jResponse:ToJson(), , 400) => definição do status HTTP de erro da requisição.
jResponse["email"] := ZT0->ZT0_EMAIL => montagem do json de resposta à requisição quando há sucesso na operação. A atribuição é repetida para as outras propriedades do json de resposta.
self:SetResponse(jResponse:ToJson()) => define a resposta que deve acontecer.
return lProcessed => indica se o processamento aconteceu com sucesso ou com erro/falha, isso indicará se o status HTTP definido pela função SetRestFault deve ser considerado. Neste exemplo quando um body é inválido (por exemplo não contém a propriedade email) é retornado status HTTP 400.

GET geral - retorna uma lista

wsmethod GET V1ALL wsreceive page, pageSize wsservice Perfis
    local lProcessed as logical
    local jResponse  as object
    local jTempItem  as object
    lProcessed := .T.

    // Define o tipo de retorno do método
    self:SetContentType("application/json")

    // As propriedades da classe receberão os valores enviados por querystring
    // exemplo: http://localhost:18085/rest/microblog/v1/perfis?page=1&pageSize=5
    default self:page := 1
    default self:pageSize := 5

    DbSelectArea("ZT0")
    DbSetOrder(3) // ZT0_FILIAL+ZT0_NOME
    DbSeek(xFilial("ZT0"))

    // exemplo de retorno de uma lista de objetos JSON
    jResponse := JsonObject():New()
    jResponse['items'] := {}
    while ZT0->(!EOF())
        aAdd(jResponse['items'], JsonObject():New())
        jTempItem := aTail(jResponse['items'])

        jTempItem["email"]   := ZT0->ZT0_EMAIL
        jTempItem["user_id"] := ZT0->ZT0_USRID
        jTempItem["name"]    := ZT0->ZT0_NOME
        // jTempItem["inserted_at"] := ZT0->S_T_A_M_P_
        // jTempItem["updated_at"] := ZT0->I_N_S_D_T_
        ZT0->(DbSkip())
    end

    self:SetResponse(jResponse:ToJson())
return lProcessed

wsreceive page, pageSize => este trecho determina que as propriedades page e pageSize podem ser preenchidas com o conteúdo oferecido pelos parâmetros de path ou query. Neste caso são de query indicador por ?page=2&pageSize=15 na montagem da URL requisitada.
default self:page := 1 => como parâmetros de query não são obrigatórios o default garante algum valor. Estes parâmetros somente serão usados em versões mais sofisticadas, pois seria complicado implementar paginação com esta versão simplificada do serviço rest em Advpl.
jResponse['items'] := {} => a resposta ao serviço é uma lista então é definida a propriedade items como array em Advpl.
aAdd(jResponse['items'], JsonObject():New()) => um novo item é adicionado e recebe uma instância da classe JsonObject. Com o JsonObject é possível montar json de forma simplificada.
jTempItem := aTail(jResponse['items']) => recupera o último item adicionado ao array.
jTempItem["email"] := ZT0->ZT0_EMAIL => atribui as propriedades do item corrente ao json de resposta.
self:SetResponse(jResponse:ToJson()) => responde com a lista de itens recuperados da tabela ZT0.

GET um - retorna um item

wsmethod GET V1ID pathparam perfilId wsservice Perfis
    local lProcessed as logical
    local jResponse  as object

    lProcessed := .T.
    self:SetContentType("application/json")

    DbSelectArea("ZT0")
    DbSetOrder(2) // ZT0_FILIAL+ZT0_USRID

    jResponse := JsonObject():New()

    // Id não ser vazio e existir como item na tabela
    lProcessed := (!(Alltrim(self:perfilId) == "") .And. ZT0->(DbSeek(xFilial("ZT0")+self:perfilId)))
    if lProcessed

        jResponse["email"]   := ZT0->ZT0_EMAIL
        jResponse["user_id"] := ZT0->ZT0_USRID
        jResponse["name"]    := ZT0->ZT0_NOME
        // jResponse["inserted_at"] := ZT0->S_T_A_M_P_
        // jResponse["updated_at"] := ZT0->I_N_S_D_T_

        self:SetResponse(jResponse:ToJson())
    else
        jResponse["error"] := "id_invalido"
        jResponse["description"] := i18n("Perfil não encontrado utilizando o #[id] informado", {self:perfilId})

        self:SetResponse(jResponse:ToJson())
        SetRestFault(404, jResponse:ToJson(), , 404)
        lProcessed := .F.
    endif

return lProcessed

pathparam perfilId => este trecho na indicação de início do corpo do método determina o preenchimento da propriedade perfilId da classe Perfil. O parâmetro de path é obrigatório e portanto é seguro fazer o uso da propriedade sem receios.
ZT0->(DbSeek(xFilial("ZT0")+self:perfilId)) => este é um exemplo do uso da propriedade diretamente em uma pesquisa/posicionamento de registro na tabela ZT0.
Essa foi a última particularidade relacionada com classes e métodos para serviços rest e montagem de respostas destes serviços.
Os demais métodos não terão suas particularidades em puro Advpl comentadas.

PUT - altera um item e retorna este item

wsmethod PUT V1ID pathparam perfilId wsservice Perfis
    local lProcessed as logical
    local jResponse  as object

    lProcessed := .T.
    self:SetContentType("application/json")

    DbSelectArea("ZT0")
    DbSetOrder(2) // ZT0_FILIAL+ZT0_USRID

    jResponse := JsonObject():New()

    // Id não ser vazio e existir como item na tabela
    lProcessed := (!(Alltrim(self:perfilId) == "") .And. ZT0->(DbSeek(xFilial("ZT0")+self:perfilId)))
    if lProcessed

        jBody := JsonObject():New()
        jBody:FromJson(self:GetContent())

        if (jBody["name"] == Nil)
            jResponse["error"] := "body_invalido"
            jResponse["description"] := "Forneça a propriedade 'name' no body"

            self:SetResponse(jResponse:ToJson())
            SetRestFault(400, jResponse:ToJson(), , 400)
            lProcessed := .F.
        else

            Reclock("ZT0", .F.)
                ZT0->ZT0_NOME   := jBody["name"]
            ZT0->(MsUnlock())

            jResponse["email"]   := ZT0->ZT0_EMAIL
            jResponse["user_id"] := ZT0->ZT0_USRID
            jResponse["name"]    := ZT0->ZT0_NOME
            // jResponse["inserted_at"] := ZT0->S_T_A_M_P_
            // jResponse["updated_at"] := ZT0->I_N_S_D_T_

            self:SetResponse(jResponse:ToJson())
        endif
    else
        jResponse["error"] := "id_invalido"
        jResponse["description"] := i18n("Perfil não encontrado utilizando o #[id] informado", {self:perfilId})

        self:SetResponse(jResponse:ToJson())
        SetRestFault(404, jResponse:ToJson(), , 404)
        lProcessed := .F.
    endif

return lProcessed

DELETE - exclui um item

wsmethod DELETE V1 pathparam perfilId wsservice Perfis
    local lProcessed as logical
    local lDelete    as logical
    local jResponse  as object

    lProcessed := .T.
    self:SetContentType("application/json")

    DbSelectArea("ZT0")
    DbSetOrder(2) // ZT0_FILIAL+ZT0_USRID

    jResponse := JsonObject():New()

    // Id não ser vazio e existir como item na tabela
    varinfo("id", self:perfilId)
    lProcessed := !(Alltrim(self:perfilId) == "")
    if lProcessed

        // Se não encontrar o registro, não faz nada e retorna verdadeiro
        lDelete := ZT0->(DbSeek(xFilial("ZT0")+self:perfilId))
        if lDelete
            Reclock("ZT0", .F.)
                DbDelete()
            ZT0->(MsUnlock())
        endif

        self:SetResponse("{}")
    else
        jResponse["error"] := "id_invalido"
        jResponse["description"] := i18n("Perfil não encontrado utilizando o #[id] informado", {self:perfilId})

        self:SetResponse(jResponse:ToJson())
        SetRestFault(404, jResponse:ToJson(), , 404)
        lProcessed := .F.
    endif

return lProcessed

A imagem a seguir mostra o serviço de Perfis na lista.

A imagem a seguir mostra os detalhes do serviço de Perfis.

Conclusão

Este é um modo de ter as operações básicas de CRUD acontecendo em determinada tabela do sistema Protheus usando serviços Rest.
Essa implementação falha em diversos conceitos e técnicas para evitar duplicidade de código, organização e design de componentes internos e principalmente cria alto acoplamento entre ler e traduzir a requisição para uma entidade Perfil e gravar isso na tabela. Esse alto acoplamento não será endereçado tão logo.
O próximo passo será mostrar como funciona a exposição de serviços rest quando utilizado modelos MVC e qual a diferença para o CRUD construído para a tabela ZT0.

Um microblog usando Protheus - Rest Server, parte 1, o que será esta série

Josimar Junior — Sun, 22 Nov 2020 18:20:56 +0000

Introdução

Existem alguns conteúdos sobre o uso e criação de apis Rest usando o Protheus e a linguagem ADVPL, contudo pouco vai além da montagem básica dos métodos e operações padrões. Então, esta série tem o objetivo de fazer um microblog (aplicação tipo Twitter) usando o servidor Rest do Protheus com Advpl.
Para criar a api usando Advpl será necessário discutir e explicar alguns conceitos de como o Rest funciona e eventuais particularidades quando comparado com as linguagens e frameworks de mercado.
Alguns conteúdos com a documentação ou artigos com exemplos de uso são:
link 1: Web Services REST/Server
link 2: Exemplo simples
link 3: Exemplo mais complexo

O Rest no Protheus

A sequência de artigos e documentação no link 1 acima aborda de forma bem abrangente o "como funciona" e portanto para mais detalhes sugiro a leitura daquela documentação com atenção.
O Rest com Advpl no Protheus foi construído para suportar os seguintes métodos de REST sobre HTTP GET, POST, PUT, DELETE e OPTIONS.
A construção dos serviços segue um pouco do modelo das classes de serviços para Web Services SOAP e portanto, em Advpl são construídas classes WSRESTFUL e com isso alguns métodos dessas classes irão responder pelos métodos HTTP conforme a URI definida. Estes elementos serão detalhados quando os serviços começarem a ser construídos.
A execução do Rest Server acontece em duas etapas: a recepção das requisições e validação de requisições e depois o processamento e resposta. Essa divisão é importante especialmente para entender o que pode ser melhorado com relação a tempo de resposta dos serviços. É possível observar estas etapas quando é ligado o log FWTRACELOG=1 na seção do ambiente configurado para o Rest Server.
Estes são os elementos importantes no momento, caso tenha criado curiosidade sobre algum dos temas mencionados sugiro procurar ou praticar o que é mencionado nas publicações.
Importante: será utilizado Advpl em boa parte dos exemplos e não TLPP, TLPP precisará da sua própria jornada e aplicação de exemplo. Sobre a diferença de Rest com Advpl e TLPP esta documentação é um excelente ponto de partida Rest Advpl x Rest 2.0.

O projeto do microblog

Uma das maneiras para aprender e exercitar situações complexas no desenvolvimento é com a escolha de soluções para serem desenvolvidas. No passado para entender e aprender como criar, desenvolver e principalmente entender os conceitos de desenvolvimento web utilizei Ruby on Rails e segui o Rails Tutorial.
A aplicação desenvolvida é um clone do Twitter e com isso vários conceitos puderam ser abordados com relação ao construção da aplicação (CRUD simples, operações complexas, atualizações parciais e validações complexas, renderização de componentes, etc). Então utilizando como exemplo a aplicação do Rails Tutorial pensei em fazer o mesmo para apresentar a construção de uma Api Rest usando o Protheus.

O que terá no projeto?

O projeto irá conter duas entidades: Perfis e Publicações.
Estas duas entidades depois irão se relacionar e as funcionalidades disponibilizadas ao final serão:
login;
criação, atualização e inativação de perfil;
seguir perfil;
visualizar lista de seguidores e perfis seguidos;
criação de publicação;
associação de comentários;
filtro e ordenação de publicações;

A construção destes serviços envolverá passar pelo jeito tradicional (e que PRECISA mudar) de escrever programas Advpl para uma forma que permita isolar o negócio e eventualmente permitir evoluções de tecnologia que não envolva mexer na regra de de negócio.

Como acompanhar

O projeto no Github https://github.com/josimar-jr/microblog-protheus terá os códigos baseados em branches que serão mantidas conforme o projeto for evoluindo para permitir a comparação com versões anteriores dos programas.
Este projeto terá também alguns dos recursos base para conseguir replicar o ambiente utilizado e cada pessoa conseguir testar em ambiente de desenvolvimento.
Parte do desenvolvimento será apoiado com testes usando o Postman e por isso não será usado nenhum recurso de teste automatizado próprio para Protheus ou Advpl.

Até a próxima página dessa jornada.