TOTVSTEC

Árvore de páginas

Quando falamos em serviços REST, podemos ter Path Virtuais que irão compor a URI do serviço, e ao final, também a URL na qual os clientes farão requisições ao serviço.

O Path Parameter utiliza a definição do endpoint para possibilitar o envio de informações. Esses parâmetros farão parte do endpoint, porém terão dados variáveis.

Importante!

Em uma API REST, variáveis definidas via Path Parameter compõem a estrutura do endpoint e atuam como chaves identificadoras do recurso.

Quando múltiplos métodos HTTP (como GET, PUT, etc.) utilizam o mesmo caminho base com Path Parameters, o nome da variável é determinado pela primeira rota registrada no servidor.
Nomes diferentes definidos em rotas posteriores para o mesmo caminho serão ignorados.

Exemplo:

#include "tlpp-core.th"
#include "tlpp-rest.th"

@Get("/pathparamsexample/:used")
@Put("/pathparamsexample/:ignored")
function U_samplePathParam()
  local jPath as json
  jPath := oRest:getPathParamsRequest()
return oRest:SetResponse( jPath )

Chamadas:

GET http://127.0.0.1:9080/pathparamsexample/123
PUT http://127.0.0.1:9080/pathparamsexample/123

Resposta (jPath):

{
  "used": "123"
}

Observação:
Nesse cenário, o parâmetro sempre será "used", definido no primeiro endpoint (GET).
O nome "ignored", especificado no PUT, nunca será utilizado pelo mecanismo de resolução de parâmetros.

Do lado da execução do serviço, temos que nos ater não somente em como resgatar os valores, mas como também em como prover, segue:

#include "tlpp-core"
#include "tlpp-rest"
​
@Get("sample/function/pathparamsexample/:code")
user function samplePathParamsExample()
    
    local cReturn     := ""
    local jPathParams := Nil 
​
    jPathParams := oRest:getPathParamsRequest()
    if jPathParams <> Nil
        cReturn := "Parâmetros capturados: [" + jPathParams:ToJSon() + "]"
    endif
​
    oRest:SetResponse( cReturn )
​
return

Na definição do endpoint, já incluímos o parâmetro code em sua definição, e para que o REST entenda de que se trata da uma variável, colocamos ":" antes do nome da variável.

Notem que na definição do endpoint inserimos a variável code da seguinte maneira:

@Get("sample/function/pathparamsexample/:code")

Ao indicar ":" antes de code, automaticamente estamos definindo que o valor passado nessa posição da URI será nosso parâmetro de nome code e poderá ser variável, porém, para acessar esse serviço a requisição tem que respeitar o endpoint completo, tornando o parâmetro obrigatório.

Para obter todos os parâmetros enviados via Path Param, fazemos uso do método oRest:getPathParamsRequest().

Esse método já nos retorna em formato JSON, portanto, para acessar o dado de um determinado parâmetro, basta seguir como abaixo:

jPathParams := oRest:getPathParamsRequest()
    cCode := jPathParams[ 'code' ]

Para o exemplo acima funcionar, a chamada deveria ser assim:

http://localhost:8080/sample/function/pathparamsexample/1

Atenção:

Os objetos JSON retornados por métodos de oRest, como por exemplo oRest:getQueryRequest(), são referências ao objeto existente no REST e não uma cópia.

Existem alguns motivos para ser uma referência, são eles:

  • Melhorar performance do serviço;
  • Economia de memória;
  • Evitar que seja necessário limpar o objeto na saída da implementação do serviço REST.

Portanto, é imprescindível que não se manipule diretamente o Objeto, pois isso irá refletir nas próximas requisições, causando problemas difíceis de serem detectados.

Métodos:

oRest:getPathParamsRequest()
oRest:getQueryRequest()
oRest:getHeaderRequest()
oRest:getThreadPoolTlppData()
oRest:getServerTlppData()
oRest:getThreadPoolUserData()
oRest:getThreadPoolServerUserData()
oRest:getHeaderResponse()

  • Sem rótulos