Pular para conteúdo

REST e APIs

Status: parcial — afirmações verificadas, com lacunas declaradas. [n · F] remete à fonte n da lista de fontes; a letra marca a procedência: F fato em fonte oficial TOTVS/TDN · S fonte secundária (blog, fórum) · unverified sem fonte que sustente.

Escopo desta seção

Os dois lados da integração: expor serviços REST em TLPP por anotação (com o objeto oRest e documentação OpenAPI nativa) e consumir APIs externas com a classe cliente FWRest em AdvPL, incluindo autenticação.

Expor: REST no tlppCore

  • O REST do tlppCore roda dentro do AppServer, usa annotations e reflection, serviços dinâmicos, documentação OpenAPI nativa e hooks de fluxo e log.[15 · F]
  • O endpoint é declarado por annotation acima da função ou método, vinculando a rota (URN) e o verbo HTTP pertinente (@Get, @Post, @Put, @Delete ou @Patch).[16 · F]
  • Propriedades da annotation: endpoint é obrigatória e define a rota; description é opcional e fornece uma descrição informativa.[44 · F]
  • Includes obrigatórios são tlpp-core.th e tlpp-rest.th, ambos já presentes nativamente no tlpp.rpo; a resposta sai por oRest:setResponse().[16 · F]
  • O objeto oRest expõe getPathParamsRequest() para os path params em JSON, getQueryRequest(), GetBodyRequest(), setResponse(), setStatusCode() e setFault().[17 · F]
  • A annotation independe de classes e pode ser usada diretamente em uma User Function, sem WSRESTFUL ou WSMETHOD do modelo legado.[17 · F]
  • Comparativo de verbos: o FWREST legado cobre GET, POST, PUT e DELETE; o TLPP Core cobre GET, POST, PUT, PATCH e DELETE.[17 · F]
  • O motor de documentação REST_DOC/OpenAPI do tlppCore fica disponível a partir do tlppCore 01.04.02 com AppServer 20.3.1.10.[5, 45 · F]

Armadilha de path params

Com o mesmo caminho base, o nome da variável é o da primeira rota registrada; nomes divergentes em rotas posteriores são ignorados — silenciosamente.[17]

Consumir: cliente FWRest

  • Cliente REST em AdvPL: FWRest():new(cUrlBase), headers em array, e o token no cabeçalho Authorization com o valor Bearer mais o token de acesso.[27 · F]
  • Autenticação por Bearer token está disponível a partir da LIB 20190705; o token é obtido por POST no endpoint de token com grant_type=password, o access token expira em uma hora e o refresh em vinte e quatro horas.[27 · F]
  • A exigência de autenticação no serviço é ligada com SECURITY=1 na seção [HTTPREST] do .ini; a partir da LIB 20201019, se a chave não for informada, os serviços sobem exigindo autenticação de usuário.[58 · F]
  • Existem repositórios oficiais TOTVS de exemplo REST e de documentação OpenAPI.[7, 8 · F]

Migração de WsRESTful para o REST do tlppCore

  • Existe trilha oficial "Migração WsRESTful para REST tlppCore", de FWREST para annotations, com tabela De/Para.[17 · F]

Lacunas declaradas

Lacuna: "Padrões TTALK" — nenhuma fonte primária foi localizada. Não tratar TTALK como norma TOTVS neste wiki até haver fonte.

Lacuna: a configuração do servidor REST no appserver.ini além de SECURITY=1 (portas, troubleshooting) não foi coletada nesta passada.

Lacuna: paginação, modelo de erro e versionamento de API não têm fonte coletada.

Fontes

[5] · [7] · [8] · [15] · [16] · [17] · [27] · [44] · [45] · [58] — ver lista completa.