REST v31 20220708 - 230205

You are using an UNLICENSED copy of Scroll PDF Exporter for Confluence.
Do you find Scroll PDF Exporter useful? Consider purchasing it today: https://www.k15t.com/software/scroll-pdf-exporter
REST
TOTVSTEC
Exported on 07/08/2022

TOTVSTEC – REST
You are using an UNLICENSED copy of Scroll PDF Exporter for Confluence. Do you find Scroll PDF Exporter useful? Consider purchasing it today: https://www.k15t.com/software/scroll-pdf-exporter
Table of Contents
1 REST server (tlppCore)......................................................................................21
2 1 - Primeiros Passos ..........................................................................................25
2.1 A - Configuração básica ......................................................................................................... 25
2.1.1 Via INI .................................................................................................................................................................... 25
2.1.1.1 Configuração Rest Server TLPP via INI................................................................................................................ 25
2.1.2 Via JSON ( código fonte ) ..................................................................................................................................... 27
2.1.2.1 Configuração Rest Server TLPP via JSON ........................................................................................................... 27
2.2 B - Ambiente de compilação do TLPP................................................................................... 33
2.2.1 Ambiente de desenvolvimento do TL++ ............................................................................................................. 33
2.2.1.1 Extraindo os includes........................................................................................................................................... 33
2.3 C - Criando primeiro serviço ( Hello World ).......................................................................... 34
2.3.1 Meu primeiro programa....................................................................................................................................... 34
2.3.1.1 Utilizando função................................................................................................................................................. 34
2.3.1.2 Utilizando classe .................................................................................................................................................. 35
2.3.1.3 Explicando os componentes ............................................................................................................................... 35
2.4 D - Entendendo a composição da URL.................................................................................. 36
2.4.1 HOST | (http://127.0.0.1:8080/) e (https://127.0.0.1:444/).................................................................................. 37
2.4.1.1 Protocolo | (http://) e (https://) ........................................................................................................................... 37
2.4.1.2 Porta | (:8080) e (:444) .......................................................................................................................................... 38
2.4.2 Path Virtual | (/totvs) ............................................................................................................................................ 38
2.4.3 Endpoint | (/api/sample)...................................................................................................................................... 39
2.4.3.1 Annotation............................................................................................................................................................ 39
2.4.3.2 JSON ..................................................................................................................................................................... 39
2.4.4 Parâmetros via Query String | (param1=value) .................................................................................................. 39
3 2 - Configurações Avançadas............................................................................40
3.1 A - Verbos/Métodos disponíveis (@annotation)................................................................... 40
3.1.1 @DELETE()............................................................................................................................................................ 42
3.1.1.1 Exemplo utilizando função e recebendo parâmetro via path param ............................................................... 42
3.1.1.2 Exemplo utilizando função recebendo parâmetro via query string.................................................................. 43
3.1.1.3 Exemplo utilizando classe com métodos e recebendo parâmetro via path param e query string. ................ 43
3.1.2 @GET() .................................................................................................................................................................. 44
– 2
TOTVSTEC – REST
3.1.2.2 Exemplo utilizando função e recebendo parâmetro via query string............................................................... 45

3.1.2.3 Exemplo utilizando classe com métodos recebendo parâmetro via path param e query string. ................... 45
3.1.3 @PATCH() ............................................................................................................................................................. 46
3.1.4 @POST() ............................................................................................................................................................... 48
3.1.5 @PUT().................................................................................................................................................................. 50
3.1.5.2 Exemplo utilizando função recebendo parâmetro via query string.................................................................. 51
3.2 B - Serviços sem uso de @Annotation .................................................................................. 53
3.2.1 Inicialização de um serviço REST ........................................................................................................................ 53
3.2.2 Vinculando a URN à API ....................................................................................................................................... 54
3.2.2.1 OBSERVAÇÃO........................................................................................................................................................ 55
3.3 C - Configuração completa .................................................................................................... 56
3.3.1 Charset.................................................................................................................................................................. 57
3.3.2 ContentTypes (Sessão) ........................................................................................................................................ 58
3.3.2.1 Exemplos de configuração .................................................................................................................................. 59
3.3.3 HTTPSERVER (sessão).......................................................................................................................................... 59
3.3.3.1 Chaves da sessão ................................................................................................................................................. 59
3.3.3.2 Exemplos de ativação .......................................................................................................................................... 60
3.3.4 locations (chave) .................................................................................................................................................. 61
3.3.4.1 Exemplos de configuração - 1 {locations} somente ........................................................................................... 61
3.3.4.2 Exemplos de configuração - 2 {locations}........................................................................................................... 61
3.3.5 LOCATIONS (Sessão)............................................................................................................................................ 62
3.3.5.1 Chaves da sessão ................................................................................................................................................. 62
3.3.6 servers (chave) ..................................................................................................................................................... 63
3.3.6.1 Exemplos de configuração - 1 {servers} somente............................................................................................... 63
3.3.6.2 Exemplos de configuração - 2 {servers} .............................................................................................................. 64
3.3.7 SERVERS (Sessão) ................................................................................................................................................ 64
– 3
TOTVSTEC – REST
3.3.7.1 Chaves da sessão ................................................................................................................................................. 65


3.3.8 SLAVE (Sessão) ..................................................................................................................................................... 67
3.3.8.1 Chaves da sessão ................................................................................................................................................. 68
3.3.9 THREADPOOL (Sessão) ........................................................................................................................................ 69
3.3.9.1 Chaves da sessão ................................................................................................................................................. 70
3.3.9.2 Observações ......................................................................................................................................................... 71
3.3.10 tlppData (chave)................................................................................................................................................... 72
3.3.10.1 O que é? ................................................................................................................................................................ 72
3.3.10.2 Configuração ........................................................................................................................................................ 72
3.3.10.3 Como se utilizam? ................................................................................................................................................ 73
3.3.11 userData (chave) .................................................................................................................................................. 73
3.3.11.1 O que é? ................................................................................................................................................................ 73
3.3.11.2 Como usar?........................................................................................................................................................... 74
3.3.11.3 Onde usar?............................................................................................................................................................ 75
3.3.11.4 Configuração ........................................................................................................................................................ 75
3.3.11.5 Como resgatar os valores de userData ............................................................................................................... 76
3.3.12 UserExits (chave).................................................................................................................................................. 78
3.3.12.1 O que são? ............................................................................................................................................................ 78
3.3.12.2 Configuração ........................................................................................................................................................ 78
3.3.12.3 Como se utilizam? ................................................................................................................................................ 79
3.3.13 UserExits (Sessão) ................................................................................................................................................ 80
3.3.13.1 Chaves da sessão ................................................................................................................................................. 80
4 3 - Funções de Usuário......................................................................................82
4.1 onError.................................................................................................................................... 82
4.1.1 Parâmetros........................................................................................................................................................... 82
4.1.2 Retorno ................................................................................................................................................................. 82
4.1.3 Exemplo................................................................................................................................................................ 82
4.2 onSelect.................................................................................................................................. 83
4.2.1 Parâmetros........................................................................................................................................................... 83
4.2.2 Retorno ................................................................................................................................................................. 84
4.2.3 Exemplo................................................................................................................................................................ 84
4.3 onStart.................................................................................................................................... 85
– 4
TOTVSTEC – REST
4.3.1 Parâmetros........................................................................................................................................................... 85
4.3.2 Retorno ................................................................................................................................................................. 85

4.3.3 Exemplo................................................................................................................................................................ 86
4.4 onStop .................................................................................................................................... 86
4.4.1 Parâmetros........................................................................................................................................................... 86
4.4.2 Retorno ................................................................................................................................................................. 86
4.4.3 Exemplo................................................................................................................................................................ 86
5 4 - Entendendo o objeto oREST........................................................................87

5.1 A - O que é oRest?................................................................................................................... 87
5.2 B - Resgatando valores da requisição ................................................................................... 87
5.2.1 Body...................................................................................................................................................................... 87
5.2.2 HTTP Header (requisição).................................................................................................................................... 88
5.2.3 Path Param........................................................................................................................................................... 89
5.2.4 Query String ......................................................................................................................................................... 90
5.3 C - Definindo as respostas ..................................................................................................... 91
5.3.1 Corpo da Mensagem ............................................................................................................................................ 91
5.3.1.1 Exemplo 1 (simples)............................................................................................................................................. 91
5.3.1.2 Exemplo 2 (resposta segmentada)...................................................................................................................... 92
5.3.1.3 Exemplo 3 ("resetando" a resposta) ................................................................................................................... 92
5.3.2 Formato da Mensagem ........................................................................................................................................ 93
5.3.2.1 Exemplo................................................................................................................................................................ 93
5.3.3 HTTP Header (resposta) ...................................................................................................................................... 93
5.3.4 HTTP Status Code ................................................................................................................................................ 93
5.3.4.1 Exemplo 1 (simples)............................................................................................................................................. 94
5.3.4.2 Exemplo 2 ("resetando" o status) ....................................................................................................................... 94
5.3.5 Mensagem de erro................................................................................................................................................ 95
5.3.5.1 Exemplo utilizando a forma mais simples de geração de erro.......................................................................... 95
5.3.5.2 Exemplo utilizando 2 métodos............................................................................................................................ 96
5.4 D - Todos os métodos ............................................................................................................ 96
5.4.1 Namespace........................................................................................................................................................... 96
5.4.2 Hierarquia............................................................................................................................................................. 97
5.4.3 Propriedades ........................................................................................................................................................ 97
5.4.4 Métodos ................................................................................................................................................................ 97
5.4.4.1 Exemplos .............................................................................................................................................................. 98
– 5
TOTVSTEC – REST
5.4.4.2 Abrangência ......................................................................................................................................................... 98

5.4.5 oRest:appendKeyHeaderResponse .................................................................................................................... 99

5.4.5.1 Sintaxe .................................................................................................................................................................. 99
5.4.5.2 Parâmetros........................................................................................................................................................... 99
5.4.5.3 Retorno ................................................................................................................................................................. 99
5.4.5.4 Exemplos .............................................................................................................................................................. 99
5.4.5.5 Abrangência ....................................................................................................................................................... 100
5.4.6 oRest:deleteKeyHeaderResponse..................................................................................................................... 100
5.4.6.1 Sintaxe ................................................................................................................................................................ 100
5.4.6.2 Parâmetros......................................................................................................................................................... 100
5.4.6.3 Retorno ............................................................................................................................................................... 100
5.4.6.4 Exemplos ............................................................................................................................................................ 100
5.4.6.5 Abrangência ....................................................................................................................................................... 101
5.4.7 oRest:existKeyHeaderRequest .......................................................................................................................... 101
5.4.7.1 Sintaxe ................................................................................................................................................................ 101
5.4.7.2 Parâmetros......................................................................................................................................................... 101
5.4.7.3 Retorno ............................................................................................................................................................... 101
5.4.7.4 Observações ....................................................................................................................................................... 101
5.4.7.5 Exemplos ............................................................................................................................................................ 101
5.4.7.6 Abrangência ....................................................................................................................................................... 102
5.4.8 oRest:getBodyRequest ...................................................................................................................................... 102
5.4.8.1 Sintaxe ................................................................................................................................................................ 102
5.4.8.2 Retorno ............................................................................................................................................................... 102
5.4.8.3 Observações ....................................................................................................................................................... 102
5.4.8.4 Exemplos ............................................................................................................................................................ 102
5.4.8.5 Abrangência ....................................................................................................................................................... 103
5.4.8.6 versão: 01.02.04.................................................................................................................................................. 103
5.4.9 oRest:getCentryPointAuthorizationOnAuth..................................................................................................... 103
5.4.9.1 Sintaxe ................................................................................................................................................................ 103
5.4.9.2 Retorno ............................................................................................................................................................... 103
5.4.9.3 Exemplos ............................................................................................................................................................ 103
5.4.9.4 Abrangência ....................................................................................................................................................... 104
5.4.9.5 Veja também ...................................................................................................................................................... 104
5.4.10 oRest:getCentryPointAuthorizationScheme .................................................................................................... 104
5.4.10.1 Sintaxe ................................................................................................................................................................ 104
– 6
TOTVSTEC – REST
5.4.10.2 Retorno ............................................................................................................................................................... 104

5.4.10.3 Observações ....................................................................................................................................................... 104

5.4.10.4 Exemplos ............................................................................................................................................................ 104
5.4.10.5 Abrangência ....................................................................................................................................................... 104
5.4.11 oRest:getCentryPointEnvironment................................................................................................................... 105
5.4.11.1 Sintaxe ................................................................................................................................................................ 105
5.4.11.2 Retorno ............................................................................................................................................................... 105
5.4.11.3 Exemplos ............................................................................................................................................................ 105
5.4.11.4 Abrangência ....................................................................................................................................................... 105
5.4.11.5 Veja também ...................................................................................................................................................... 105
5.4.12 oRest:getCentryPointError ................................................................................................................................ 105
5.4.12.1 Sintaxe ................................................................................................................................................................ 106
5.4.12.2 Retorno ............................................................................................................................................................... 106
5.4.12.3 Exemplos ............................................................................................................................................................ 106
5.4.12.4 Abrangência ....................................................................................................................................................... 106
5.4.12.5 Veja também ...................................................................................................................................................... 106
5.4.13 oRest:getCEntryPointExit .................................................................................................................................. 106
5.4.13.1 Sintaxe ................................................................................................................................................................ 106
5.4.13.2 Retorno ............................................................................................................................................................... 107
5.4.13.3 Exemplos ............................................................................................................................................................ 107
5.4.13.4 Abrangência ....................................................................................................................................................... 107
5.4.13.5 Veja também ...................................................................................................................................................... 107
5.4.14 oRest:getCEntryPointGrader ............................................................................................................................. 107
5.4.14.1 Sintaxe ................................................................................................................................................................ 107
5.4.14.2 Retorno ............................................................................................................................................................... 108
5.4.14.3 Exemplos ............................................................................................................................................................ 108
5.4.14.4 Abrangência ....................................................................................................................................................... 108
5.4.14.5 Veja também ...................................................................................................................................................... 108
5.4.15 oRest:getCloseAfterSend................................................................................................................................... 108
5.4.15.1 Sintaxe ................................................................................................................................................................ 108
5.4.15.2 Retorno ............................................................................................................................................................... 109
5.4.15.3 Observações ....................................................................................................................................................... 109
5.4.15.4 Exemplos ............................................................................................................................................................ 109
5.4.15.5 Abrangência ....................................................................................................................................................... 109
5.4.16 oRest:getConnectionRequest............................................................................................................................ 109
– 7
TOTVSTEC – REST
5.4.16.1 Sintaxe ................................................................................................................................................................ 109

5.4.16.2 Retorno ............................................................................................................................................................... 109

5.4.16.3 Observações ....................................................................................................................................................... 110
5.4.16.4 Exemplos ............................................................................................................................................................ 110
5.4.16.5 Abrangência ....................................................................................................................................................... 110
5.4.17 oRest:getHeaderRequest................................................................................................................................... 110
5.4.17.1 Sintaxe ................................................................................................................................................................ 110
5.4.17.2 Retorno ............................................................................................................................................................... 110
5.4.17.3 Observações ....................................................................................................................................................... 110
5.4.17.4 Exemplos ............................................................................................................................................................ 111
5.4.17.5 Abrangência ....................................................................................................................................................... 111
5.4.18 oRest:getHeaderResponse ................................................................................................................................ 111
5.4.18.1 Sintaxe ................................................................................................................................................................ 111
5.4.18.2 Retorno ............................................................................................................................................................... 111
5.4.18.3 Observações ....................................................................................................................................................... 111
5.4.18.4 Exemplos ............................................................................................................................................................ 112
5.4.18.5 Abrangência ....................................................................................................................................................... 112
5.4.19 oRest:getKeyHeaderResponse .......................................................................................................................... 112
5.4.19.1 Sintaxe ................................................................................................................................................................ 112
5.4.19.2 Parâmetros......................................................................................................................................................... 112
5.4.19.3 Retorno ............................................................................................................................................................... 112
5.4.19.4 Observações ....................................................................................................................................................... 113
5.4.19.5 Exemplos ............................................................................................................................................................ 113
5.4.19.6 Abrangência ....................................................................................................................................................... 113
5.4.20 oRest:getLentryPointAuthorization .................................................................................................................. 113
5.4.20.1 Sintaxe ................................................................................................................................................................ 113
5.4.20.2 Retorno ............................................................................................................................................................... 113
5.4.20.3 Exemplos ............................................................................................................................................................ 113
5.4.20.4 Abrangência ....................................................................................................................................................... 114
5.4.20.5 Veja também ...................................................................................................................................................... 114
5.4.21 oRest:getLEntryPointExit .................................................................................................................................. 114
5.4.21.1 Sintaxe ................................................................................................................................................................ 114
5.4.21.2 Retorno ............................................................................................................................................................... 114
5.4.21.3 Exemplos ............................................................................................................................................................ 114
5.4.21.4 Abrangência ....................................................................................................................................................... 115
– 8
TOTVSTEC – REST
5.4.21.5 Veja também ...................................................................................................................................................... 115

5.4.22 oRest:getLEntryPointGrader ............................................................................................................................. 115

5.4.22.1 Sintaxe ................................................................................................................................................................ 115
5.4.22.2 Retorno ............................................................................................................................................................... 115
5.4.22.3 Exemplos ............................................................................................................................................................ 115
5.4.22.4 Abrangência ....................................................................................................................................................... 116
5.4.22.5 Veja também ...................................................................................................................................................... 116
5.4.23 oRest:getMethodRequest .................................................................................................................................. 116
5.4.23.1 Sintaxe ................................................................................................................................................................ 116
5.4.23.2 Retorno ............................................................................................................................................................... 116
5.4.23.3 Exemplos ............................................................................................................................................................ 116
5.4.23.4 Abrangência ....................................................................................................................................................... 116
5.4.24 oRest:getPathParamsRequest .......................................................................................................................... 117
5.4.24.1 Sintaxe ................................................................................................................................................................ 117
5.4.24.2 Retorno ............................................................................................................................................................... 117
5.4.24.3 Observações ....................................................................................................................................................... 117
5.4.24.4 Exemplos ............................................................................................................................................................ 117
5.4.24.5 Abrangência ....................................................................................................................................................... 117
5.4.25 oRest:getPathRequest ....................................................................................................................................... 118
5.4.25.1 Sintaxe ................................................................................................................................................................ 118
5.4.25.2 Retorno ............................................................................................................................................................... 118
5.4.25.3 Exemplos ............................................................................................................................................................ 118
5.4.25.4 Abrangência ....................................................................................................................................................... 118
5.4.26 oRest:getProtocolRequest................................................................................................................................. 118
5.4.26.1 Sintaxe ................................................................................................................................................................ 118
5.4.26.2 Retorno ............................................................................................................................................................... 119
5.4.26.3 Exemplos ............................................................................................................................................................ 119
5.4.26.4 Abrangência ....................................................................................................................................................... 119
5.4.27 oRest:getQueryRequest..................................................................................................................................... 119
5.4.27.1 Sintaxe ................................................................................................................................................................ 119
5.4.27.2 Retorno ............................................................................................................................................................... 119
5.4.27.3 Observações ....................................................................................................................................................... 119
5.4.27.4 Exemplos ............................................................................................................................................................ 120
5.4.27.5 Abrangência ....................................................................................................................................................... 120
5.4.28 oRest:getRetCodResponse ................................................................................................................................ 120
– 9
TOTVSTEC – REST
5.4.28.1 Sintaxe ................................................................................................................................................................ 120

5.4.28.2 Retorno ............................................................................................................................................................... 120

5.4.28.3 Observações ....................................................................................................................................................... 120
5.4.28.4 Exemplos ............................................................................................................................................................ 121
5.4.28.5 Abrangência ....................................................................................................................................................... 121
5.4.29 oRest:getRetMsgResponse ................................................................................................................................ 121
5.4.29.1 Sintaxe ................................................................................................................................................................ 121
5.4.29.2 Retorno ............................................................................................................................................................... 121
5.4.29.3 Observações ....................................................................................................................................................... 121
5.4.29.4 Exemplos ............................................................................................................................................................ 121
5.4.29.5 Abrangência ....................................................................................................................................................... 122
5.4.30 oRest:getStatusResponse.................................................................................................................................. 122
5.4.30.1 Sintaxe ................................................................................................................................................................ 122
5.4.30.2 Retorno ............................................................................................................................................................... 122
5.4.30.3 Observações ....................................................................................................................................................... 122
5.4.30.4 Exemplos ............................................................................................................................................................ 122
5.4.30.5 Abrangência ....................................................................................................................................................... 122
5.4.31 oRest:getThreadIdRequest................................................................................................................................ 123
5.4.31.1 Sintaxe ................................................................................................................................................................ 123
5.4.31.2 Retorno ............................................................................................................................................................... 123
5.4.31.3 Observações ....................................................................................................................................................... 123
5.4.31.4 Exemplos ............................................................................................................................................................ 123
5.4.31.5 Abrangência ....................................................................................................................................................... 123
5.4.32 oRest:getThreadPool_SvcId_TPType ............................................................................................................... 123
5.4.32.1 Sintaxe ................................................................................................................................................................ 124
5.4.32.2 Retorno ............................................................................................................................................................... 124
5.4.32.3 Observações ....................................................................................................................................................... 124
5.4.32.4 Exemplos ............................................................................................................................................................ 124
5.4.32.5 Abrangência ....................................................................................................................................................... 124
5.4.33 oRest:getThreadPoolAcceptTimeout ............................................................................................................... 124
5.4.33.1 Sintaxe ................................................................................................................................................................ 124
5.4.33.2 Retorno ............................................................................................................................................................... 125
5.4.33.3 Observações ....................................................................................................................................................... 125
5.4.33.4 Exemplos ............................................................................................................................................................ 125
5.4.33.5 Abrangência ....................................................................................................................................................... 125
– 10
TOTVSTEC – REST
5.4.34 oRest:getThreadPoolAuthorizationScheme..................................................................................................... 125

5.4.34.1 Sintaxe ................................................................................................................................................................ 125

5.4.34.2 Retorno ............................................................................................................................................................... 126
5.4.34.3 Exemplos ............................................................................................................................................................ 126
5.4.34.4 Abrangência ....................................................................................................................................................... 126
5.4.35 oRest:getThreadPoolEnvironment ................................................................................................................... 126
5.4.35.1 Sintaxe ................................................................................................................................................................ 126
5.4.35.2 Retorno ............................................................................................................................................................... 126
5.4.35.3 Observações ....................................................................................................................................................... 126
5.4.35.4 Exemplos ............................................................................................................................................................ 127
5.4.35.5 Abrangência ....................................................................................................................................................... 127
5.4.36 oRest:getThreadPoolGrowthFactor.................................................................................................................. 127
5.4.36.1 Sintaxe ................................................................................................................................................................ 127
5.4.36.2 Retorno ............................................................................................................................................................... 127
5.4.36.3 Observações ....................................................................................................................................................... 127
5.4.36.4 Exemplos ............................................................................................................................................................ 127
5.4.36.5 Abrangência ....................................................................................................................................................... 128
5.4.37 oRest:getThreadPoolId...................................................................................................................................... 128
5.4.37.1 Sintaxe ................................................................................................................................................................ 128
5.4.37.2 Retorno ............................................................................................................................................................... 128
5.4.37.3 Observações ....................................................................................................................................................... 128
5.4.37.4 Exemplos ............................................................................................................................................................ 128
5.4.37.5 Abrangência ....................................................................................................................................................... 129
5.4.38 oRest:getThreadPoolInactiveTimeout.............................................................................................................. 129
5.4.38.1 Sintaxe ................................................................................................................................................................ 129
5.4.38.2 Retorno ............................................................................................................................................................... 129
5.4.38.3 Observações ....................................................................................................................................................... 129
5.4.38.4 Exemplos ............................................................................................................................................................ 129
5.4.38.5 Abrangência ....................................................................................................................................................... 130
5.4.39 oRest:getThreadPoolMaxThreads..................................................................................................................... 130
5.4.39.1 Sintaxe ................................................................................................................................................................ 130
5.4.39.2 Retorno ............................................................................................................................................................... 130
5.4.39.3 Observações ....................................................................................................................................................... 130
5.4.39.4 Exemplos ............................................................................................................................................................ 130
5.4.39.5 Abrangência ....................................................................................................................................................... 131
– 11
TOTVSTEC – REST
5.4.40 oRest:getThreadPoolMinFreeThreads.............................................................................................................. 131

5.4.40.1 Sintaxe ................................................................................................................................................................ 131

5.4.40.2 Retorno ............................................................................................................................................................... 131
5.4.40.3 Observações ....................................................................................................................................................... 131
5.4.40.4 Exemplos ............................................................................................................................................................ 131
5.4.40.5 Abrangência ....................................................................................................................................................... 131
5.4.41 oRest:getThreadPoolMinThreads ..................................................................................................................... 132
5.4.41.1 Sintaxe ................................................................................................................................................................ 132
5.4.41.2 Retorno ............................................................................................................................................................... 132
5.4.41.3 Observações ....................................................................................................................................................... 132
5.4.41.4 Exemplos ............................................................................................................................................................ 132
5.4.41.5 Abrangência ....................................................................................................................................................... 132
5.4.42 oRest:getThreadPoolName ............................................................................................................................... 133
5.4.42.1 Sintaxe ................................................................................................................................................................ 133
5.4.42.2 Retorno ............................................................................................................................................................... 133
5.4.42.3 Observações ....................................................................................................................................................... 133
5.4.42.4 Exemplos ............................................................................................................................................................ 133
5.4.42.5 Abrangência ....................................................................................................................................................... 133
5.4.43 oRest:getThreadPoolServerUserData............................................................................................................... 133
5.4.43.1 Sintaxe ................................................................................................................................................................ 134
5.4.43.2 Retorno ............................................................................................................................................................... 134
5.4.43.3 Observações ....................................................................................................................................................... 134
5.4.43.4 Exemplos ............................................................................................................................................................ 134
5.4.43.5 Abrangência ....................................................................................................................................................... 134
5.4.44 oRest:getThreadPoolServiceId.......................................................................................................................... 134
5.4.44.1 Sintaxe ................................................................................................................................................................ 135
5.4.44.2 Retorno ............................................................................................................................................................... 135
5.4.44.3 Exemplos ............................................................................................................................................................ 135
5.4.44.4 Abrangência ....................................................................................................................................................... 135
5.4.45 oRest:getThreadPoolServiceName................................................................................................................... 135
5.4.45.1 Sintaxe ................................................................................................................................................................ 135
5.4.45.2 Retorno ............................................................................................................................................................... 135
5.4.45.3 Observações ....................................................................................................................................................... 136
5.4.45.4 Exemplos ............................................................................................................................................................ 136
5.4.45.5 Abrangência ....................................................................................................................................................... 136
– 12
TOTVSTEC – REST
5.4.46 oRest:getThreadPoolServicePort...................................................................................................................... 136

5.4.46.1 Sintaxe ................................................................................................................................................................ 136

5.4.46.2 Retorno ............................................................................................................................................................... 136
5.4.46.3 Observações ....................................................................................................................................................... 136
5.4.46.4 Exemplos ............................................................................................................................................................ 137
5.4.46.5 Abrangência ....................................................................................................................................................... 137
5.4.47 oRest:getThreadPoolServiceSSL....................................................................................................................... 137
5.4.47.1 Sintaxe ................................................................................................................................................................ 137
5.4.47.2 Retorno ............................................................................................................................................................... 137
5.4.47.3 Observações ....................................................................................................................................................... 137
5.4.47.4 Exemplos ............................................................................................................................................................ 137
5.4.47.5 Abrangência ....................................................................................................................................................... 138
5.4.48 oRest:getThreadPoolSlaves .............................................................................................................................. 138
5.4.48.1 Sintaxe ................................................................................................................................................................ 138
5.4.48.2 Retorno ............................................................................................................................................................... 138
5.4.48.3 Observações ....................................................................................................................................................... 138
5.4.48.4 Exemplos ............................................................................................................................................................ 138
5.4.48.5 Abrangência ....................................................................................................................................................... 139
5.4.49 oRest:getThreadPoolStatus .............................................................................................................................. 139
5.4.49.1 Sintaxe ................................................................................................................................................................ 139
5.4.49.2 Retorno ............................................................................................................................................................... 139
5.4.49.3 Observações ....................................................................................................................................................... 140
5.4.49.4 Exemplos ............................................................................................................................................................ 140
5.4.49.5 Abrangência ....................................................................................................................................................... 140
5.4.50 oRest:getThreadPoolType................................................................................................................................. 140
5.4.50.1 Sintaxe ................................................................................................................................................................ 140
5.4.50.2 Retorno ............................................................................................................................................................... 140
5.4.50.3 Observações ....................................................................................................................................................... 140
5.4.50.4 Exemplos ............................................................................................................................................................ 141
5.4.50.5 Abrangência ....................................................................................................................................................... 141
5.4.51 oRest:getThreadPoolUserData ......................................................................................................................... 141
5.4.51.1 Sintaxe ................................................................................................................................................................ 141
5.4.51.2 Retorno ............................................................................................................................................................... 141
5.4.51.3 Observações ....................................................................................................................................................... 141
5.4.51.4 Exemplos ............................................................................................................................................................ 141
– 13
TOTVSTEC – REST
5.4.51.5 Abrangência ....................................................................................................................................................... 142

5.4.52 oRest:getThreadPoolUserExitName ................................................................................................................. 142

5.4.52.1 Sintaxe ................................................................................................................................................................ 142
5.4.52.2 Retorno ............................................................................................................................................................... 142
5.4.52.3 Exemplos ............................................................................................................................................................ 142
5.4.52.4 Abrangência ....................................................................................................................................................... 142
5.4.53 oRest:getThreadPoolUserExitOnError.............................................................................................................. 143
5.4.53.1 Sintaxe ................................................................................................................................................................ 143
5.4.53.2 Retorno ............................................................................................................................................................... 143
5.4.53.3 Exemplos ............................................................................................................................................................ 143
5.4.53.4 Abrangência ....................................................................................................................................................... 143
5.4.54 oRest:getThreadPoolUserExitOnSelect ............................................................................................................ 143
5.4.54.1 Sintaxe ................................................................................................................................................................ 143
5.4.54.2 Retorno ............................................................................................................................................................... 143
5.4.54.3 Exemplos ............................................................................................................................................................ 143
5.4.54.4 Abrangência ....................................................................................................................................................... 144
5.4.55 oRest:getThreadPoolUserExitOnStart .............................................................................................................. 144
5.4.55.1 Sintaxe ................................................................................................................................................................ 144
5.4.55.2 Retorno ............................................................................................................................................................... 144
5.4.55.3 Exemplos ............................................................................................................................................................ 144
5.4.55.4 Abrangência ....................................................................................................................................................... 144
5.4.56 oRest:getThreadPoolUserExitOnStop .............................................................................................................. 144
5.4.56.1 Sintaxe ................................................................................................................................................................ 144
5.4.56.2 Retorno ............................................................................................................................................................... 144
5.4.56.3 Exemplos ............................................................................................................................................................ 145
5.4.56.4 Abrangência ....................................................................................................................................................... 145
5.4.57 oRest:httpCallEnd .............................................................................................................................................. 145
5.4.57.1 Sintaxe ................................................................................................................................................................ 145
5.4.57.2 Retorno ............................................................................................................................................................... 145
5.4.57.3 Observações ....................................................................................................................................................... 145
5.4.57.4 Exemplos ............................................................................................................................................................ 145
5.4.57.5 Abrangência ....................................................................................................................................................... 145
5.4.57.6 Veja também ...................................................................................................................................................... 146
5.4.58 oRest:resetMessageResponse ........................................................................................................................... 146
5.4.58.1 Sintaxe ................................................................................................................................................................ 146
– 14
TOTVSTEC – REST
5.4.58.2 Retorno ............................................................................................................................................................... 146

5.4.58.3 Observações ....................................................................................................................................................... 146

5.4.58.4 Exemplos ............................................................................................................................................................ 146
5.4.58.5 Abrangência ....................................................................................................................................................... 146
5.4.59 oRest:resetResponse ......................................................................................................................................... 147
5.4.59.1 Sintaxe ................................................................................................................................................................ 147
5.4.59.2 Retorno ............................................................................................................................................................... 147
5.4.59.3 Observações ....................................................................................................................................................... 147
5.4.59.4 Exemplos ............................................................................................................................................................ 147
5.4.59.5 Abrangência ....................................................................................................................................................... 147
5.4.60 oRest:resetStatusCode ...................................................................................................................................... 148
5.4.60.1 Sintaxe ................................................................................................................................................................ 148
5.4.60.2 Retorno ............................................................................................................................................................... 148
5.4.60.3 Observações ....................................................................................................................................................... 148
5.4.60.4 Exemplos ............................................................................................................................................................ 148
5.4.60.5 Abrangência ....................................................................................................................................................... 149
5.4.61 oRest:sendZipped .............................................................................................................................................. 149
5.4.61.1 Sintaxe ................................................................................................................................................................ 149
5.4.61.2 Parâmetros......................................................................................................................................................... 149
5.4.61.3 Retorno ............................................................................................................................................................... 149
5.4.61.4 Observações ....................................................................................................................................................... 149
5.4.61.5 Exemplos ............................................................................................................................................................ 149
5.4.61.6 Abrangência ....................................................................................................................................................... 150
5.4.62 oRest:setCloseAfterSend ................................................................................................................................... 150
5.4.62.1 Sintaxe ................................................................................................................................................................ 150
5.4.62.2 Parâmetros......................................................................................................................................................... 150
5.4.62.3 Retorno ............................................................................................................................................................... 151
5.4.62.4 Observações ....................................................................................................................................................... 151
5.4.62.5 Exemplos ............................................................................................................................................................ 151
5.4.62.6 Abrangência ....................................................................................................................................................... 151
5.4.63 oRest:setFault .................................................................................................................................................... 151
5.4.63.1 Sintaxe ................................................................................................................................................................ 151
5.4.63.2 Parâmetros......................................................................................................................................................... 151
5.4.63.3 Retorno ............................................................................................................................................................... 152
5.4.63.4 Observações ....................................................................................................................................................... 152
– 15
TOTVSTEC – REST
5.4.63.5 Exemplos ............................................................................................................................................................ 152

5.4.63.6 Abrangência ....................................................................................................................................................... 152

5.4.64 oRest:setHeaderResponse ................................................................................................................................ 152
5.4.64.1 Rest:setHeaderResponse................................................................................................................................... 152
5.4.65 oRest:setHttpEnd............................................................................................................................................... 154
5.4.65.1 Sintaxe ................................................................................................................................................................ 154
5.4.65.2 Retorno ............................................................................................................................................................... 154
5.4.65.3 Observações ....................................................................................................................................................... 154
5.4.65.4 Exemplos ............................................................................................................................................................ 154
5.4.65.5 Abrangência ....................................................................................................................................................... 154
5.4.66 oRest:setKeyHeaderResponse .......................................................................................................................... 155
5.4.66.1 Sintaxe ................................................................................................................................................................ 155
5.4.66.2 Parâmetros......................................................................................................................................................... 155
5.4.66.3 Retorno ............................................................................................................................................................... 155
5.4.66.4 Exemplos ............................................................................................................................................................ 155
5.4.66.5 Abrangência ....................................................................................................................................................... 155
5.4.67 oRest:setResponse............................................................................................................................................. 156
5.4.67.1 Sintaxe ................................................................................................................................................................ 156
5.4.67.2 Parâmetros......................................................................................................................................................... 156
5.4.67.3 Retorno ............................................................................................................................................................... 156
5.4.67.4 Observações ....................................................................................................................................................... 156
5.4.67.5 Exemplos ............................................................................................................................................................ 156
5.4.67.6 Abrangência ....................................................................................................................................................... 157
5.4.68 oRest:setStatusCode.......................................................................................................................................... 157
5.4.68.1 Sintaxe ................................................................................................................................................................ 157
5.4.68.2 Parâmetros......................................................................................................................................................... 157
5.4.68.3 Retorno ............................................................................................................................................................... 157
5.4.68.4 Observações ....................................................................................................................................................... 157
5.4.68.5 Exemplos ............................................................................................................................................................ 157
5.4.68.6 Abrangência ....................................................................................................................................................... 158
5.4.69 oRest:updateKeyHeaderResponse ................................................................................................................... 158
5.4.69.1 Sintaxe ................................................................................................................................................................ 158
5.4.69.2 Parâmetros......................................................................................................................................................... 158
5.4.69.3 Retorno ............................................................................................................................................................... 158
5.4.69.4 Exemplos ............................................................................................................................................................ 158
– 16
TOTVSTEC – REST
5.4.69.5 Abrangência ....................................................................................................................................................... 159

5.4.70 Rest:ExistKeyHeaderResponse.......................................................................................................................... 159

5.4.70.1 Sintaxe ................................................................................................................................................................ 159
5.4.70.2 Parâmetros......................................................................................................................................................... 159
5.4.70.3 Retorno ............................................................................................................................................................... 159
5.4.70.4 Observações ....................................................................................................................................................... 159
5.4.70.5 Exemplos ............................................................................................................................................................ 159
5.4.70.6 Abrangência ....................................................................................................................................................... 160
5.4.71 Rest:getBodyResponse ...................................................................................................................................... 160
5.4.71.1 Sintaxe ................................................................................................................................................................ 160
5.4.71.2 Retorno ............................................................................................................................................................... 160
5.4.71.3 Observações ....................................................................................................................................................... 160
5.4.71.4 Exemplos ............................................................................................................................................................ 160
5.4.71.5 Abrangência ....................................................................................................................................................... 161
5.4.72 Rest:getFullURLRequest .................................................................................................................................... 161
5.4.72.1 Sintaxe ................................................................................................................................................................ 161
5.4.72.2 Retorno ............................................................................................................................................................... 161
5.4.72.3 Exemplos ............................................................................................................................................................ 161
5.4.72.4 Abrangência ....................................................................................................................................................... 162
5.4.73 Rest:getLentryPointEnvironment ..................................................................................................................... 162
5.4.73.1 Sintaxe ................................................................................................................................................................ 162
5.4.73.2 Retorno ............................................................................................................................................................... 162
5.4.73.3 Exemplos ............................................................................................................................................................ 162
5.4.73.4 Abrangência ....................................................................................................................................................... 163
5.4.73.5 Veja também ...................................................................................................................................................... 163
5.4.74 Rest:getLEntryPointError .................................................................................................................................. 163
5.4.74.1 Sintaxe ................................................................................................................................................................ 163
5.4.74.2 Retorno ............................................................................................................................................................... 163
5.4.74.3 Exemplos ............................................................................................................................................................ 163
5.4.74.4 Abrangência ....................................................................................................................................................... 164
5.4.74.5 Veja também ...................................................................................................................................................... 164
5.4.75 Rest:getThreadPoolAuthorizationOnAuth ....................................................................................................... 164
5.4.75.1 Sintaxe ................................................................................................................................................................ 164
5.4.75.2 Retorno ............................................................................................................................................................... 164
5.4.75.3 Exemplos ............................................................................................................................................................ 164
– 17
TOTVSTEC – REST
5.4.75.4 Abrangência ....................................................................................................................................................... 164

5.4.76 Rest:getURLRequest .......................................................................................................................................... 165

5.4.76.1 Sintaxe ................................................................................................................................................................ 165
5.4.76.2 Retorno ............................................................................................................................................................... 165
5.4.76.3 Exemplos ............................................................................................................................................................ 165
5.4.76.4 Abrangência ....................................................................................................................................................... 165
5.4.77 Rest:getUserExit ................................................................................................................................................. 165
5.4.77.1 Sintaxe ................................................................................................................................................................ 166
5.4.77.2 Retorno ............................................................................................................................................................... 166
5.4.77.3 Exemplos ............................................................................................................................................................ 166
5.4.77.4 Abrangência ....................................................................................................................................................... 166
5.4.77.5 Veja também ...................................................................................................................................................... 166
5.4.78 Rest:getXhrRequest ........................................................................................................................................... 166
5.4.78.1 Sintaxe ................................................................................................................................................................ 167
5.4.78.2 Retorno ............................................................................................................................................................... 167
5.4.78.3 Observações ....................................................................................................................................................... 167
5.4.78.4 Exemplos ............................................................................................................................................................ 167
5.4.78.5 Abrangência ....................................................................................................................................................... 167
5.4.79 Rest:setUserExit ................................................................................................................................................. 167
5.4.79.1 Sintaxe ................................................................................................................................................................ 168
5.4.79.2 Parâmetros......................................................................................................................................................... 168
5.4.79.3 Retorno ............................................................................................................................................................... 168
5.4.79.4 Exemplos ............................................................................................................................................................ 168
5.4.79.5 Abrangência ....................................................................................................................................................... 168
5.4.79.6 Veja também ...................................................................................................................................................... 168
5.5 E - Todas as funções............................................................................................................. 169
5.5.1 Namespace......................................................................................................................................................... 169
5.5.2 Funções .............................................................................................................................................................. 169
5.5.2.1 Abrangência ....................................................................................................................................................... 169
5.5.3 wsRestfulStart .................................................................................................................................................... 169
5.5.3.1 Namespace......................................................................................................................................................... 169
5.5.3.2 Sintaxe ................................................................................................................................................................ 169
5.5.3.3 Parâmetros......................................................................................................................................................... 169
5.5.3.4 Retorno ............................................................................................................................................................... 170
5.5.3.5 Exemplos ............................................................................................................................................................ 170
– 18
TOTVSTEC – REST
5.5.3.6 Abrangência ....................................................................................................................................................... 171

6 5 - APIs .............................................................................................................172
6.1 Configuração em tempo real............................................................................................... 172
6.1.1 Como utilizar ...................................................................................................................................................... 172
6.2 Lista de Serviços disponíveis............................................................................................... 173
6.2.1 Como utilizar ...................................................................................................................................................... 173
6.2.1.1 Via User Function ............................................................................................................................................... 174
6.2.1.2 Via Classe ............................................................................................................................................................ 174
6.2.2 Funcionamento.................................................................................................................................................. 175
6.3 Métricas de tempos.............................................................................................................. 175
6.3.1 Como utilizar ...................................................................................................................................................... 175
6.3.1.1 Utilizando User Function. .................................................................................................................................. 178
6.3.1.2 Utilizando Classe................................................................................................................................................ 178
6.3.2 Funcionamento.................................................................................................................................................. 179
6.4 Monitoramento .................................................................................................................... 179
6.4.1 Monitoramento .................................................................................................................................................. 179
6.4.1.1 Como utilizar ...................................................................................................................................................... 179
6.4.1.2 Funcionamento.................................................................................................................................................. 182
6.5 Versão ................................................................................................................................... 182
6.5.1 Como utilizar ...................................................................................................................................................... 182
6.5.1.1 /totvs/environment............................................................................................................................................ 183
6.5.1.2 Utilizando User Function. .................................................................................................................................. 183
6.5.1.3 Utilizando Classe................................................................................................................................................ 184
6.5.2 Funcionamento.................................................................................................................................................. 185
7 6 - Exemplos práticos......................................................................................186
7.1 CRUD..................................................................................................................................... 186
7.2 Migração WsRESTful para REST tlppCore ........................................................................... 186
7.2.1 Como migrar um REST em FWREST para uso com Annotation (tlppCore) ..................................................... 186
7.2.1.1 Características.................................................................................................................................................... 187
7.2.1.2 Resumo das mudanças...................................................................................................................................... 187
7.2.1.3 Exemplos ............................................................................................................................................................ 190
8 Authentication ................................................................................................194
8.1 oAuth .................................................................................................................................... 194
– 19
TOTVSTEC – REST
8.1.1 Basic.................................................................................................................................................................... 194

8.1.2 Configuração ...................................................................................................................................................... 194

8.1.3 BASIC: Como se utiliza? ..................................................................................................................................... 195
8.1.3.1 Parâmetros......................................................................................................................................................... 195
8.1.3.2 Retorno ............................................................................................................................................................... 196
8.1.3.3 Exemplo.............................................................................................................................................................. 196
8.2 oAuth2 .................................................................................................................................. 197
8.2.1 Refresh Token .................................................................................................................................................... 198
8.2.2 Token de Acesso................................................................................................................................................. 199
8.2.3 Utilizando o Protocolo oAuth2 .......................................................................................................................... 201
8.3 Configuração do Ambiente.................................................................................................. 202
8.3.1 onAuth ................................................................................................................................................................ 203
8.3.2 onAuthNoCheckUri ............................................................................................................................................ 204
8.3.3 onAuthparams.................................................................................................................................................... 205
8.3.3.1 Definição............................................................................................................................................................. 205
8.3.3.2 Informações importantes .................................................................................................................................. 205
8.3.3.3 Observações ....................................................................................................................................................... 206
8.3.3.4 Utilização............................................................................................................................................................ 207
– 20
TOTVSTEC – REST
1 REST server (tlppCore)

REST que significa Representational State Transfer, trata-se de uma abstração da arquitetura da Web.
Para saber mais detalhes sobre REST, sugerimos ler a publicação em nosso blog1.
A linguagem TL++ chega trazendo alguns pontos interessantes a serem considerados quando falamos desta
tecnologia, tais como :
• Um server nativo no servidor de aplicação (Appserver), proporcionando ganho de performance e
estabilidade.
• Simplicidade na implementação das aplicações através do uso de Reflections e Annotations2 , possibilitando
que aplicações possam ser escritas em fontes separados.
• Configuração, início e parada do serviço, tudo através de código fonte. Obviamente que o modo (INI)
tradicional é mantido.
• Manipulação das configurações do REST Server sem a necessidade de parada do serviço, através de API.
Para que seja possível usufruir dos benefícios citados acima e muitos outros proporcionados pela linguagem TL++
para o desenvolvimento de uma aplicação REST sugerimos que sejam seguidos os passos abaixo:
• 1 - Primeiros Passos(see page 25)

• A - Configuração básica(see page 25)
• Via INI(see page 25)
• Via JSON ( código fonte )(see page 27)
• B - Ambiente de compilação do TLPP(see page 33)
• C - Criando primeiro serviço ( Hello World )(see page 34)
• D - Entendendo a composição da URL(see page 36)
• 2 - Configurações Avançadas(see page 40)
• A - Verbos/Métodos disponíveis (@annotation)(see page 40)
• @DELETE()(see page 42)
• @GET()(see page 44)
• @PATCH()(see page 46)
• @POST()(see page 48)
• @PUT()(see page 50)
• B - Serviços sem uso de @Annotation(see page 53)
• C - Configuração completa(see page 56)
• Charset(see page 57)
• ContentTypes (Sessão)(see page 58)
• HTTPSERVER (sessão)(see page 59)
• locations (chave)(see page 61)
• LOCATIONS (Sessão)(see page 62)
• servers (chave)(see page 63)
• SERVERS (Sessão)(see page 64)
• SLAVE (Sessão)(see page 67)
• THREADPOOL (Sessão)(see page 69)
• tlppData (chave)(see page 72)
• userData (chave)(see page 73)
• UserExits (chave)(see page 78)
• UserExits (Sessão)(see page 80)
• 3 - Funções de Usuário(see page 82)
1 https://www.totvs.com/blog/developers/rest/
2 https://tdn.totvs.com/display/tec/Reflection+e+Annotation
REST server (tlppCore) – 21

TOTVSTEC – REST
• onError(see page 82)

• onSelect(see page 83)

• onStart(see page 85)
• onStop(see page 86)
• 4 - Entendendo o objeto oREST(see page 87)
• A - O que é oRest?(see page 87)
• B - Resgatando valores da requisição(see page 87)
• Body(see page 87)
• HTTP Header (requisição)(see page 88)
• Path Param(see page 89)
• Query String(see page 90)
• C - Definindo as respostas(see page 91)
• Corpo da Mensagem(see page 91)
• Formato da Mensagem(see page 93)
• HTTP Header (resposta)(see page 93)
• HTTP Status Code(see page 93)
• Mensagem de erro(see page 95)
• D - Todos os métodos(see page 96)
• oRest:appendKeyHeaderResponse(see page 99)
• oRest:deleteKeyHeaderResponse(see page 100)
• oRest:existKeyHeaderRequest(see page 101)
• oRest:getBodyRequest(see page 102)
• oRest:getCentryPointAuthorizationOnAuth(see page 103)
• oRest:getCentryPointAuthorizationScheme(see page 104)
• oRest:getCentryPointEnvironment(see page 105)
• oRest:getCentryPointError(see page 105)
• oRest:getCEntryPointExit(see page 106)
• oRest:getCEntryPointGrader(see page 107)
• oRest:getCloseAfterSend(see page 108)
• oRest:getConnectionRequest(see page 109)
• oRest:getHeaderRequest(see page 110)
• oRest:getHeaderResponse(see page 111)
• oRest:getKeyHeaderResponse(see page 112)
• oRest:getLentryPointAuthorization(see page 113)
• oRest:getLEntryPointExit(see page 114)
• oRest:getLEntryPointGrader(see page 115)
• oRest:getMethodRequest(see page 116)
• oRest:getPathParamsRequest(see page 117)
• oRest:getPathRequest(see page 118)
• oRest:getProtocolRequest(see page 118)
• oRest:getQueryRequest(see page 119)
• oRest:getRetCodResponse(see page 120)
• oRest:getRetMsgResponse(see page 121)
• oRest:getStatusResponse(see page 122)
• oRest:getThreadIdRequest(see page 123)
• oRest:getThreadPool_SvcId_TPType(see page 123)
• oRest:getThreadPoolAcceptTimeout(see page 124)
• oRest:getThreadPoolAuthorizationScheme(see page 125)
• oRest:getThreadPoolEnvironment(see page 126)
• oRest:getThreadPoolGrowthFactor(see page 127)
• oRest:getThreadPoolId(see page 128)
• oRest:getThreadPoolInactiveTimeout(see page 129)
• oRest:getThreadPoolMaxThreads(see page 130)

TOTVSTEC – REST
• oRest:getThreadPoolMinFreeThreads(see page 131)

• oRest:getThreadPoolMinThreads(see page 132)

• oRest:getThreadPoolName(see page 133)
• oRest:getThreadPoolServerUserData(see page 133)
• oRest:getThreadPoolServiceId(see page 134)
• oRest:getThreadPoolServiceName(see page 135)
• oRest:getThreadPoolServicePort(see page 136)
• oRest:getThreadPoolServiceSSL(see page 137)
• oRest:getThreadPoolSlaves(see page 138)
• oRest:getThreadPoolStatus(see page 139)
• oRest:getThreadPoolType(see page 140)
• oRest:getThreadPoolUserData(see page 141)
• oRest:getThreadPoolUserExitName(see page 142)
• oRest:getThreadPoolUserExitOnError(see page 143)
• oRest:getThreadPoolUserExitOnSelect(see page 143)
• oRest:getThreadPoolUserExitOnStart(see page 144)
• oRest:getThreadPoolUserExitOnStop(see page 144)
• oRest:httpCallEnd(see page 145)
• oRest:resetMessageResponse(see page 146)
• oRest:resetResponse(see page 147)
• oRest:resetStatusCode(see page 148)
• oRest:sendZipped(see page 149)
• oRest:setCloseAfterSend(see page 150)
• oRest:setFault(see page 151)
• oRest:setHeaderResponse(see page 152)
• oRest:setHttpEnd(see page 154)
• oRest:setKeyHeaderResponse(see page 155)
• oRest:setResponse(see page 156)
• oRest:setStatusCode(see page 157)
• oRest:updateKeyHeaderResponse(see page 158)
• Rest:ExistKeyHeaderResponse(see page 159)
• Rest:getBodyResponse(see page 160)
• Rest:getFullURLRequest(see page 161)
• Rest:getLentryPointEnvironment(see page 162)
• Rest:getLEntryPointError(see page 163)
• Rest:getThreadPoolAuthorizationOnAuth(see page 164)
• Rest:getURLRequest(see page 165)
• Rest:getUserExit(see page 165)
• Rest:getXhrRequest(see page 166)
• Rest:setUserExit(see page 167)
• E - Todas as funções(see page 169)
• wsRestfulStart(see page 169)
• 5 - APIs(see page 172)
• Configuração em tempo real(see page 172)
• Lista de Serviços disponíveis(see page 173)
• Métricas de tempos(see page 175)
• Monitoramento(see page 179)
• Versão(see page 182)
• 6 - Exemplos práticos(see page 186)
• CRUD(see page 186)
• Migração WsRESTful para REST tlppCore(see page 186)
• Authentication(see page 194)
• oAuth(see page 194)

TOTVSTEC – REST
• oAuth2(see page 197)

• Refresh Token(see page 198)

• Token de Acesso(see page 199)
• Utilizando o Protocolo oAuth2(see page 201)
• Configuração do Ambiente(see page 202)
• onAuth(see page 203)
• onAuthNoCheckUri(see page 204)
• onAuthparams(see page 205)

TOTVSTEC – REST
2 1 - Primeiros Passos
Siga o roterio abaixo para entender e subir rapidamente um serviço REST.
• A - Configuração básica(see page 25)

• Via INI(see page 25)
• Via JSON ( código fonte )(see page 27)
• B - Ambiente de compilação do TLPP(see page 33)
• C - Criando primeiro serviço ( Hello World )(see page 34)
• D - Entendendo a composição da URL(see page 36)
2.1 A - Configuração básica

A linguagem TL++ possui um servidor Rest nativo no Appserver, mas para que ele possa ser utilizado é necessário
que se tenha o RPO exclusivo da linguagem TLPP.RPO.
Verifique se na pasta do binário onde se encontra o seu appserver.exe também exista o arquivo tlpp.rpo, caso não
exista, será necessário atualizar a sua pasta do binário com a expedição mais recente da Tecnologia TOTVS.
É possível configurar o Rest Server TL++ de duas maneiras:
1. Através do arquivo de configuração do servidor de aplicação(Appserver) appserver.ini(see page 25)
2. Utilizando um JSON a partir de uma function(see page 27)
Após seguir as instruções citadas acima é possível utilizar as facilidades proporcionadas pelo TL++ para o
desenvolvimento de API's Rest.
2.1.1 Via INI
2.1.1.1 Configuração Rest Server TLPP via INI

A seguir iremos expor somente a configuração mínima exigida para subir um serviço REST.
Para saber mais, vá a configuração completa(see page 40).
Copie o trecho abaixo e cole em seu appserver.ini onde você pretende executar o appserver.exe
[HTTPSERVER]
Enable=1
Servers=HTTP_REST
[HTTP_REST]
hostname=localhost
port=9995
locations=HTTP_ROOT
[HTTP_ROOT]
Path=/
RootPath=root/web
ThreadPool=THREAD_POOL
[THREAD_POOL]
1 - Primeiros Passos – 25
TOTVSTEC – REST
Environment=ENV
MinThreads=1
Explicando brevemente
1. HTTPSERVER
Aqui são definidas as configurações básicas para funcionamento do Rest Server.
Chave Tipo Obrigatório
Enable integer X
Servers string X
Chaves da sessão
Enable
Define se o HttpServer será ativado ao iniciar o Appserver.
1 = Ativado
0 = Destativado
Servers
Lista não vazia com os nomes dos servidores que serão ativados no start do server. Os nomes definidos nesta chave
devem ser utilizados na próxima sessão SERVERS.
2. SERVIDORES
Define as configurações de cada servidor HTTP e/ou HTTPS
Em nosso exemplo, foi usado o valor: HTTP_REST
Port integer X
Hostname string X
Locations string/ X
Chaves da sessão
Port
Define a porta em que o servidor será ativado.
Hostname
Define o nome virtual para o servidor que será ativado.
Locations
Define o nome das sessões(locations) deste servidor. O(s) nome(s) definido(s) nesta chave deverão utilizado(s) na
chave LOCATIONS.
TOTVSTEC – REST
3. LOCATIONS
Define a porta e a natureza dos dados de cada servidor.

Em nosso exemplo, foi usado o valor: HTTP_ROOT
Path string X
RootPath string X
ThreadPool string X
Chaves da sessão
Path
Path da URL que identificará o site.
RootPath
Path onde estarão os arquivos das páginas estáticas.
ThreadPool
Define qual o thread pool irá executar as requisições desta location. O nome definido nesta chave deverá ser
utilizado na sessão THREADPOOL.
4. THREADPOOL
Define as configurações do thread pool, o ambiente e as características das threads.
Em nosso exemplo, foi usado o valor: THREAD_POOL
Environment string X
MinThreads integer X
Chaves da sessão
Environment
Esta chave define o environment(ambiente) onde o REST será executado.
MinThreads
Indica a quantidade mínima de threads ativas no thread pool. O valor declarado deve ser maior que zero.
2.1.2 Via JSON ( código fonte )
2.1.2.1 Configuração Rest Server TLPP via JSON

Iremos utilizar a mesma configuração feita no item anterior.
TOTVSTEC – REST
O REST server disponibiliza o recurso de subir um serviço REST através de execução dinâmica, ou seja, após a
subida completa do servidor é possível indicar a subida de mais serviços REST a hora que desejar.
Esse modo é feito através de código-fonte e no processo de subida é preciso informar a configuração desejada
através de um JSON.
Segue exemplo:
Inicialização de um serviço REST dinamicamente
#include "tlpp-core.th"
/*
* Uso: rest.u_start
*/
namespace rest
Function u_start()
Local oVdrCtrl := Nil
Local nResult := 0
Local jo := Nil
Local cEnv := ""
Local cURLTest := ""
Local cURLTest2 := ""
Local cURLTest3 := ""
Local cGetWithoutAnnot := "test_without_annotation"
Local cGetPath := "/" + cGetWithoutAnnot
// Sessoes
Local sSS_HTTPSERVER := "HTTPSERVER"
Local sSS_ServerName := "TEST_REST_SERVER"
Local sSS_Location := "TEST_REST_LOCATION"
Local sSS_ThreadPool := "TEST_REST_THREADPOOL"
Local sSS_ContentTypes := "TEST_REST_CONTENTTYPES"
Local sSS_Slave01 := "TEST_REST_SLAVE01"
Local sSS_CORS := ""
Local sSS_UserExits := ""

Local sSS_UserExitsSlave := ""
// Variaveis
Local cAppPath := "/rest"
Local cAppRootPath := "C:\tlppCore\bin\root\web"
Local nAppPort := 10002
Local cAppSSL_Certificate := ""

Local cAppSSL_key := ""
Local cAppSSL_passphrase := ""
Local cAppSSL_method := "SSL/TLS"
TOTVSTEC – REST
Local cOnStartFunc := "rest.u_main_on_start"

Local cOnStopFunc := ""
Local cOnSelectFunc := "rest.u_main_on_select"
Local cOnErrorFunc := ""
Local cOnStartFuncSlave := "rest.u_slave_on_start"

Local cOnStopFuncSlave := ""
Local cOnSelectFuncSlave := "rest.u_slave_on_select"
Local cOnErrorFuncSlave := ""
// Habilita o uso das funcoes locais de preparacao de ambientes e selecao de

thread pool slaves e/ou tratamento da mensagem
// sSS_UserExits := "TEST_REST_UE"
// sSS_UserExitsSlave := "TEST_REST_UE_SLV"
// Obtem o environment
cEnv := GetEnvServer()
//------------------------------------------------------------------------------
// Cria o objeto de start do Server
oVdrCtrl := VdrCtrl():New()
// Cria o objeto de json com as informacoes do servico

jo := JsonObject():new()
jo[sSS_HTTPSERVER] := JsonObject():new()
jo[sSS_HTTPSERVER]['Log'] := .F.
jo[sSS_HTTPSERVER]['Servers'] := {sSS_ServerName}
jo[sSS_ServerName] := JsonObject():new()
jo[sSS_ServerName]['HostName'] := "Meu servidor rest"
jo[sSS_ServerName]['Port'] := nAppPort
jo[sSS_ServerName]['Charset'] := "UTF8"
jo[sSS_ServerName]['Locations'] := {sSS_Location}
If(!Empty(cAppSSL_Certificate))
jo[sSS_ServerName]['SslCertificate'] := cAppSSL_Certificate
If(!Empty(cAppSSL_key))
jo[sSS_ServerName]['SslCertificateKey'] := cAppSSL_key
EndIf
If(!Empty(cAppSSL_passphrase))
jo[sSS_ServerName]['SslCertificatePass'] := cAppSSL_passphrase
EndIf
If(!Empty(cAppSSL_method))
jo[sSS_ServerName]['SslMethod'] := cAppSSL_method
EndIf
cURLTest := "https://"
Else
TOTVSTEC – REST
cURLTest := "http://"
EndIf
If(!Empty(sSS_ContentTypes))
jo[sSS_ServerName]['ContentTypes'] := sSS_ContentTypes
EndIf
jo[sSS_Location] := JsonObject():new()
jo[sSS_Location]['Path'] := cAppPath
jo[sSS_Location]['RootPath'] := cAppRootPath
jo[sSS_Location]['DefaultPage'] := {"index.html"}
jo[sSS_Location]['ThreadPool'] := sSS_ThreadPool
jo[sSS_ThreadPool] := JsonObject():new()
jo[sSS_ThreadPool]['Environment'] := cEnv
jo[sSS_ThreadPool]['MinThreads'] := 1
jo[sSS_ThreadPool]['MaxThreads'] := 5
jo[sSS_ThreadPool]['GrowthFactor'] := 1
jo[sSS_ThreadPool]['MinFreeThreads'] := 1
jo[sSS_ThreadPool]['InactiveTimeout'] := 180000 // 180 segundos
jo[sSS_ThreadPool]['AcceptTimeout'] := 5000 // 5 segundos
If(!Empty(sSS_UserExits))
jo[sSS_ThreadPool]['UserExits'] := sSS_UserExits
jo[sSS_UserExits] := JsonObject():new()
If(!Empty(cOnStartFunc))
jo[sSS_UserExits]['OnStart'] := cOnStartFunc
EndIf
If(!Empty(cOnStopFunc))
jo[sSS_UserExits]['OnStop'] := cOnStopFunc
EndIf
If(!Empty(cOnSelectFunc))
jo[sSS_UserExits]['OnSelect'] := cOnSelectFunc
EndIf
If(!Empty(cOnErrorFunc))
jo[sSS_UserExits]['OnError'] := cOnErrorFunc
EndIf
EndIf
If(!Empty(sSS_Slave01))
jo[sSS_ThreadPool]['Slaves'] := {sSS_Slave01}
jo[sSS_Slave01] := JsonObject():new()
jo[sSS_Slave01]['Environment'] := cEnv
jo[sSS_Slave01]['MinThreads'] := 1
jo[sSS_Slave01]['MaxThreads'] := 5
jo[sSS_Slave01]['MinFreeThreads'] := 1
jo[sSS_Slave01]['GrowthFactor'] := 1
If(!Empty(sSS_UserExitsSlave))
TOTVSTEC – REST
jo[sSS_Slave01]['UserExits'] := sSS_UserExitsSlave
jo[sSS_UserExitsSlave] := JsonObject():new()
If(!Empty(cOnStartFuncSlave))
jo[sSS_UserExitsSlave]['OnStart'] := cOnStartFuncSlave
EndIf
If(!Empty(cOnStopFuncSlave))
jo[sSS_UserExitsSlave]['OnStop'] := cOnStopFuncSlave
EndIf
If(!Empty(cOnSelectFuncSlave))
jo[sSS_UserExitsSlave]['OnSelect'] := cOnSelectFuncSlave
EndIf
If(!Empty(cOnErrorFuncSlave))
jo[sSS_UserExitsSlave]['OnError'] := cOnErrorFuncSlave
EndIf
EndIf
EndIf
If(!Empty(sSS_ContentTypes))
jo[sSS_ContentTypes] := JsonObject():new()
jo[sSS_ContentTypes]['htm'] := "text/html"
jo[sSS_ContentTypes]['html'] := "text/html"
jo[sSS_ContentTypes]['json'] := "application/json"
jo[sSS_ContentTypes]['js'] := "application/javascript"
jo[sSS_ContentTypes]['txt'] := "text/plain"
jo[sSS_ContentTypes]['*'] := "application/octet-stream"
EndIf
If (!Empty(sSS_CORS))
jo[sSS_Location]['CORS'] := {sSS_CORS}
jo[sSS_CORS] := JsonObject():new()
jo[sSS_CORS]['AllowOrigins'] := {"http://127.0.0.1:8080","http://
localhost:8080"}
jo[sSS_CORS]['AllowMethods'] := {"POST", "GET", "PUT", "DELETE", "PATCH"}
EndIf
// Criar uma URN diretamente (sem annotation)

If (!Empty(cGetWithoutAnnot))
jEndpoints := JsonObject():new()
jo[sSS_ServerName]['LoadURNs'] := jEndpoints
jEndpoints[cGetPath] := JsonObject():new()
jEndpoints[cGetPath]['GET'] := JsonObject():new()
jEndpoints[cGetPath]['GET']['ClassName'] := ""
jEndpoints[cGetPath]['GET']['Function'] :=
"rest.u_getWithoutAnnotation"
jEndpoints[cGetPath]['GET']['EndPoint'] := {cGetWithoutAnnot, "get"}
EndIf
TOTVSTEC – REST
ConOut("Starting rest server on port: " + cValToChar(jo[sSS_ServerName]['Port']))

nResult := oVdrCtrl:Start(jo)
If(ValType(nResult) == 'N' .AND. nResult == 0)

ConOut("Rest server started")
cURLTest += "localhost:"
cURLTest += cValToChar(jo[sSS_ServerName]['Port'])
cURLTest += jo[sSS_Location]['Path']
cURLTest2 := cURLTest
cURLTest3 := cURLTest
cURLTest += "/tlpp/environment"
cURLTest2 += "/test"
cURLTest3 += cGetPath
ConOut("To test try on browser: ")

ConOut(cURLTest)
ConOut(cURLTest2)
ConOut(cURLTest3)
ConOut("")
Return .T.
Else
// Falhou
ConOut("Fail to start rest server [" + cValToChar(nResult) + "] - " +
cValToChar(oVdrCtrl:nErr) + " - " + cValToChar(oVdrCtrl:cErr))
Return .F.
EndIf
Return .F.
@Get("/test")
Function u_getWithAnnotation()
oRest:setResponse(time() + " " + "Hello TL++ World")
Return .T.
Function u_getWithoutAnnotation()
oRest:setResponse(time() + " " + "Hello TL++ World - Without Annotation")
Return .T.
Function u_main_on_start()
ConOut(cValToChar(ThreadId()) + " MAIN: " + ProcName())
Return .T.
Function u_main_on_select()
ConOut(cValToChar(ThreadId()) + " MAIN: " + ProcName())
Return -1
Function u_slave_on_start()
ConOut(cValToChar(ThreadId()) + " SLAVE: " + ProcName())
Return .T.
TOTVSTEC – REST
Function u_slave_on_select()
ConOut(cValToChar(ThreadId()) + " SLAVE: " + ProcName())
Return 0
> Para saber mais sobre **LoadURNs**, acesse a documentação [REST sem uso de annotation](https://
tdn.totvs.com/pages/viewpage.action?pageId=553343250(see page 53)).
2.2 B - Ambiente de compilação do TLPP
2.2.1 Ambiente de desenvolvimento do TL++

Para criarmos os programas em TL++ para o servidor REST usando os @annotation ou as classes, precisamos
preparar nosso ambiente de desenvolvimento.
O ambiente de desenvolvimento para escrever aplicações REST requer alguns includes que são distribuídos junto
com o RPO padrão do TL++ (tlpp.rpo).
Caso queria atualizar o tlpp.rpo consulte a página de Downloads do TLPP3.
2.2.1.1 Extraindo os includes

Como os includes fazem parte do RPO (tlpp.rpo), basta executar a função tlpp.environment.getIncludesTLPP para
extraí-los.
Após executar esta função os includes serão extraídos dentro do diretório do "RootPath" do seu ambiente4, em um
diretório chamado "includes".
Tendo isto basta adcionar este diretório nos seus "PATHs de includes" no seu ambiente de compilação.
• Exemplo de configuração no VS Code com o plugin da TOTVS5
Obs. os includes estão disponíveis a partir da versão 01.02.02 do RPO (tlpp.rpo)
Para extrair podemos executar esta função de diversas maneiras:

• Usando o próprio AppServer via linha de comandos:
[AppServer] -env=[seu ambiente] -run=tlpp.environment.getIncludesTLPP
Ex:
appserver.exe -env=TLPPCORE -run=tlpp.environment.getIncludesTLPP
• Usando o SmartClient:
Abrir o SmartClient e digitar na tela:
• Programa inicial: tlpp.environment.getIncludesTLPP
• Comunicação no cliente: [seu serviço]
3 https://tdninterno.totvs.com/display/tec/Downloads
4 https://tdn.totvs.com/pages/viewpage.action?spaceKey=tec&title=RootPath
5 https://www.youtube.com/watch?v=MwIu01Ztfvg&t=172s
TOTVSTEC – REST
• Ambiente no servidor: [seu ambiente]

• Usando o SmartClient via linha de comandos:

[SmartClient] -M -Q -E=[seu ambiente] -Z=[hostname /
IP]-Y=[Porta] -P=tlpp.environment.getIncludesTLPP
Ex:
smartclient.exe -M -Q -E=TLPPCORE -Z=localhost -Y=5012 -P=tlpp.environment.getIncludesTLPP
• Via código TL++ ou AdvPL:

Function u_TLPPIncs()
Local lRet := .F.
Local cRet := ""
Local aMessages := {}
Local nI := 0
ConOut("Getting TLPP includes ...")

lRet := tlpp.environment.getIncludesTLPP(@cRet, @aMessages)
If(lRet != .T.)
ConOut("Error: " + cValToChar(cRet))
For nI := 1 to Len(aMessages)
ConOut(cValToChar(nI) + " Error: " + cValToChar(aMessages[nI]))
Next
Else
ConOut("OK. 'includes' extracted on path: " + cValToChar(cRet))
EndIf
Return lRet
Obs. Você pode criar fontes .tlpp e/ou .prw sem nenhum include se eles não tiverem nenhuma dependência
2.3 C - Criando primeiro serviço ( Hello World )

Após efetuar as configurações pertinentes ao Rest Server6, veremos a partir daqui como utilizar as funcionalidades
da linguagem TL++ para escrever aplicações REST.
2.3.1 Meu primeiro programa

Como não poderia ser diferente vamos começar pelo básico, então nada melhor do que escrever nosso "Hello
World".
Podemos escrever o programa de duas maneiras:
• Utilizando uma função.
• Utilizando uma classe.
2.3.1.1 Utilizando função

#include 'tlpp-core.th'
#include 'tlpp-rest.th'
6 //tdn.totvs.com/rest_server.md
TOTVSTEC – REST
@Get("/test/helloWorld")
Function u_helloWorld()
Local cReturn := "Meu primeiro REST em TL++ " as character
oRest:setResponse(cReturn)
Return .T.
2.3.1.2 Utilizando classe

class helloWorld
public data cReturn as character
public method new()
public method sayHello() as logical
endClass
method new() class helloWorld

::cReturn := "Meu primeiro REST em TL++ "
return self
method sayHello() as logical class helloWorld

oRest:setResponse(::cReturn)
return .T.
2.3.1.3 Explicando os componentes

Tomando como base os exemplos vistos acima, vamos explicar os componentes utilizados na construção do
serviço REST TL++:
Includes
As includes tlpp-core.th e tlpp-rest.th são as únicas bibliotecas necessárias para o funcionamento básico
que qualquer função\classe REST.
As mesmas já se encontram inclusas no tlpp.rpo bastando apenas declará-las.
@Get
A utilização de annotations tornou possível a simplificação na escrita de funções\classes REST. Com elas a
aplicação faz o vínculo entre: verbo(delete,get,path,post,put) , a URN e a função/método responsável.
TOTVSTEC – REST
Saiba mais sobre a annotation @Get7

oRest:setResponse("mensagem retorno")
oRest:setResponse(::cReturn)
Este método é o responsável por enviar a mensagem de retorno no corpo da requisição para o client(requisitante).
Neste exemplo está sendo retornado uma mensagem simples, mas é possivel efetuar o retorno de todos os
formatos nas permitidos para respostas de requisições HTTP em API´s do tipo REST.
Saiba mais sobre o método setResponse()8
2.4 D - Entendendo a composição da URL

Ao acessar um serviço REST, sempre temos a URL completa em mãos para poder fazer a requisição, caso contrário,
não é possível acessar.
Porém, como a URL é composta com base na configuração do REST e criação dos serviços?
Podemos dizer que é composta por 4 partes de informações, 3 fixas e 1 não obrigatória, sendo:
Fixa
• Host;
• Path Virtual;
• Endpoint.
Não obrigatória
• Parâmetros via Query String.
Vamos ver os exemplo abaixo:
http://127.0.0.1:8080/totvs/api/sample?param1=value
e
https://127.0.0.1:444/totvs/api/sample?param1=value
Utilizando os exemplos acima, vamos segmentá-los conforme as 4 partes citadas:

• Host
http://127.0.0.1:8080/
https://127.0.0.1:444/
• Path Virtual
/totvs
• Endpoint
/api/sample
7 //tdn.totvs.com/annotationsRest.md#@Get
8 //tdn.totvs.com/classRest.md#setResponse
TOTVSTEC – REST
• Parâmetros via Query String

?param1=value
Agora, olhando parte a parte, conseguimos entender melhor de onde vem cada informação, vamos a elas:
2.4.1 HOST | (http://127.0.0.1:8080/) e (https://127.0.0.1:444/)

O Host é composto por 3 definições:
• Protocolo;
• Hostname ou IP;
• Porta.
Duas partes são definidas pela configuração diretamente no serviço do REST, ou seja, o [Protocolo] e a [Porta] são
de responsabilidade de cada execução da aplicação.
Porém, o [Hostname ou IP] são definidos pela Infraestrutura de rede e vai depender de muitas variações para
saber o valor correto, pois é preciso saber se será somente um serviço interno, se estará publicado para a Internet,
regras de redirecionamento de IPs, publicação de DNS. Essa definição não será alvo desse documento, sugerimos
sempre envolver os profissionais de Infraestrutura e Segurança da Informação para auxiliá-lo nessa tarefa.
2.4.1.1 Protocolo | (http://) e (https://)

O Protocolo pode ser HTTP ou HTTPS, sendo o primeiro o protocolo simples e o segundo o protocolo utilizando
criptografia, e nesse caso precisa de chaves de criptografias.
Para definir qual protocolo o serviço responderá, basta seguir com as configurações abaixo:
HTTP
[HTTPSERVER]
Enable=1
Servers=HTTP_SERVER
[HTTP_SERVER]
port=8080
Note que as chaves SslCertificate e SslCertificateKey são inexistentes na configuração do server, sendo assim o REST
já assume o protocolo HTTP.
HTTPS
[HTTPSERVER]
Enable=1
Servers=HTTP_SSL_SERVER
[HTTP_SSL_SERVER]
port=444
SslCertificate=SSL_certificate.crt
TOTVSTEC – REST
SslCertificateKey=SSL_certificate_key.pem
Note que nesse caso, as chaves SslCertificate e SslCertificateKey são informadas na configuração do server, sendo
assim o REST já assume o protocolo HTTPS.
Importante saber que se não informar o caminho path completo, os arquivos precisam estar na pasta BIN onde é
executado o appserver
2.4.1.2 Porta | (:8080) e (:444)

Olhando o exemplo acima, talvez você já tenha percebido onde se define a porta, mas iremos repetir para melhorar
a fixação da informação.
A porta é definida na sessão do Server, sendo:
[HTTPSERVER]
Enable=1
Servers=HTTP_SERVER
[HTTP_SERVER]
port=8080
Obviamente, para cada server é preciso definir uma porta diferente.

Para uma mesma execução do appserver, é possível subir diversos servers com portas distintas.
Para saber mais sobre definição de servers, acesse aqui(see page 64).
2.4.2 Path Virtual | (/totvs)

O Path Virtual é muito útil para distinguir tipos de serviços, e ele é definido em cada LOCATION.
Utilizando um dos exemplos acima, veja como foi configurado:
[HTTPSERVER]
Enable=1
Servers=HTTP_SSL_SERVER
[HTTP_SSL_SERVER]
locations=HTTP_ROOT
[HTTP_ROOT]
Path=/totvs
Para saber mais sobre definição de Locations, acesse aqui(see page 62).
TOTVSTEC – REST
2.4.3 Endpoint | (/api/sample)

O Endpoint não faz parte da configuração do server, e sim já é a construção de cada funcionalidade que será
disponibilizada, ou seja, é definida e criada via programação (código-fonte)
Para o REST do tlppCore, é possível definir de duas maneiras, via Annotation e via JSON e abaixo iremos mostrar
ambas.
2.4.3.1
Annotation
@Get( endpoint="/api/sample" )
user function apiSample()
......
oRest:setResponse(cJson)
return
Para saber mais sobre como criar serviços via Annotation, veja a documentação completa aqui(see page 40).
2.4.3.2 JSON
user function sLoadURNs()
local cGetPath := "/api/sample"
jEndpoints := jsonObject():New()
jEndpoints[cGetPath]['GET']['Function'] := "U_apiSample"
jEndpoints[cGetPath]['GET']['EndPoint'] := {"api","sample"}
return jEndpoints
Para saber mais sobre como criar serviços via JSON, veja a documentação completa aqui(see page 53).
2.4.4 Parâmetros via Query String | (param1=value)

Os parâmetros via Query String não são definidos pela configuração e nem diretamente definidos via criação do
serviço.
Porém, fazem parte da composição da URL pois quando internamente o serviço espera receber um valor variável
via parâmetro do tipo Query String, esse valor é obrigatóriamente passado na URL com padrão {chave=valor}.
Essa parte da composição não é obrigatória, pois o serviço pode não receber valores via Query String, portanto não
existirá essa informação na URL e mesmo assim o serviço funcionará perfeitamente.
Para saber mais sobre uso de Query String, acesse aqui(see page 90).
TOTVSTEC – REST
3 2 - Configurações Avançadas
No item anterior, aprendemos o básico para configurar e criar um serviço REST.

Agora, iremos descrever todas as funcionalidades disponibilizadas e como configurá-las para que você aprender
todo o poder do REST tlppCore.
Aproveite!
Veja mais em:
• A - Verbos/Métodos disponíveis (@annotation)(see page 40)

• B - Serviços sem uso de @Annotation(see page 53)
• C - Configuração completa(see page 56)
• Charset(see page 57)
• ContentTypes (Sessão)(see page 58)
• HTTPSERVER (sessão)(see page 59)
• locations (chave)(see page 61)
• LOCATIONS (Sessão)(see page 62)
• servers (chave)(see page 63)
• SERVERS (Sessão)(see page 64)
• SLAVE (Sessão)(see page 67)
• THREADPOOL (Sessão)(see page 69)
• tlppData (chave)(see page 72)
• userData (chave)(see page 73)
• UserExits (chave)(see page 78)
• UserExits (Sessão)(see page 80)
3.1 A - Verbos/Métodos disponíveis (@annotation)

O modo mais simples de utilizar e quais verbos/métodos o serviço REST irá responder é através de Annotations.
A utilização do recurso de annotations na linguagem TL++ possibilitou a simplificação da escrita nas aplicações
REST.
Os verbos/métodos HTTP comuns utilizados nestes tipos de requisições já estão com as suas respectivas
annotations configuradas prontas para serem utilizadas.
Atualmente, temos disponíveis os verbos/métodos mais usados em serviços REST, sendo:
• GET
O método GET solicita a representação de um recurso específico. Requisições utilizando o método GET
devem retornar apenas dados.
• POST
O método POST é utilizado para adicionar recursos no servidor REST. Se for um serviço que seja o cadastro
de clientes, o método POST irá criar um registro novo referente a um cliente novo.
2 - Configurações Avançadas – 40
TOTVSTEC – REST
• PUT
O método PUT modifica um recurso existente no servidor. Na semântica usada em modo geral, pelo método
PUT enviamos todos os dados do recurso, independentemente se serão modificados somente partes dos
dados.
• PATCH
O método PATCH modifica um recurso existente no servidor. Na semântica usada em modo geral, pelo
método PATCH enviamos somente os dados que serão modificados.
• DELETE
O método DELETE é usado para apagar um recurso no servidor REST.
Nota: Embora os métodos PUT e PATCH sejam usados semanticamente de forma diferentes, tecnicamente não há
exigência para que as aplicações serem implementadas desse modo.
Existem implementações que utilizam Criar e Modificar recursos através de um único método, ou seja, POST, PUT e
PATCH são usados através, por exemplo, do método POST e o tratamento é feito na lógica implementada no
servidor.
Embora não esteja de acordo com a semântica proposta, não significa que esteja errado.
A annotation utiliza duas propriedades, embora somente 1 é essencial para o funcionamento do serviço, sendo:
• endpoint Essa propriedade é obrigatória e é responsável para definir o endpoint utilizado na URL para que
o usuário possa fazer uma requisição ao serviço.
• description É somente a descrição, não é obrigatória e tem a finalidade somente para escrever para que
ser o serviço.
Abaixo iremos exemplificar um método GET, informando todas as propriedades, e somente a endpoint em suas
duas formas.
#include "tlpp-rest.th"
/*
Exemplo 01
Informamos as duas propriedades.

Note que nesse modo, é obrigatório informar nominalmente as propriedades.
*/
@Get( endpoint="sample/full", description='exemplo usando as duas propriedades'
)
user function sampleFull()
......

return

/*
Exemplo 02
Informamos somente endpoint, que é obrigatória.
TOTVSTEC – REST
Note que informamos nominalmente a propriedade.

*/
@Get( endpoint="sample/onlyEndpoint1" )
user function sampleOnlyEndpoint1()
......

return

/*
Exemplo 03
Informamos somente endpoint, que é obrigatória.

Note que informamos NÃO nominalmente a propriedade, esse é modo mais simples de
utilizar a annotation, pois irá atribuir o valor informado automaticamente para
o endpoint.
*/
@Get( "sample/onlyEndpoint2" )
user function sampleOnlyEndpoint2()
......

return
Abaixo é possível saber mais sobre cada verbo/método:

3.1.1 @DELETE()
Esta annotation deve ser utilizada quando for necessário desenvolver uma aplicação que responderá pelo método/
verbo DELETE. Este método/verbo deleta o recurso especificado. Abaixo veremos exemplos de sua utilização:
3.1.1.1 Exemplo utilizando função e recebendo parâmetro via path param

/* --------------------------------------------- */
@Delete("examples/function/delete/path/user/:user")
User Function examplesFunctionDeletePath()
Local cJson := ""
TOTVSTEC – REST
Local jPath
jPath := JsonObject():New()
jPath := oRest:getPathParamsRequest()
If (jPath <> Nil)

cJson := '[ { "description": "examplesFunctionDeletePath successfully
executed, parameter received: ' + jPath['user'] +'"} ]'
Endif
Return oRest:setResponse(cJson)
3.1.1.2 Exemplo utilizando função recebendo parâmetro via query string

/* --------------------------------------------- */
@Delete("examples/function/delete/query/user")
User Function examplesFunctionDeleteQuery()
Local cJson := ""
Local jQuery
jQuery := JsonObject():New()
jQuery := oRest:getQueryRequest()
If (jQuery <> Nil)

cJson := '[ {"description": "examplesFunctionDeleteQuery successfully
executed, parameter received: ' + jQuery['user'] + '"} ]'
Endif
3.1.1.3 Exemplo utilizando classe com métodos e recebendo parâmetro via path param e query
string.
Class classDeleteExamples
Public Method New()

Public Method methodExamplesDeletePath()
Public Method methodExamplesDeleteQuery()
EndClass
Method New() class classDeleteExamples
Return self
TOTVSTEC – REST
/* --------------------------------------------- */
@Delete("examples/class/delete/path/user/:user")
Method methodExamplesDeletePath() class classDeleteExamples
Local cJson := ""

Local jPath
If (jPath <> Nil)

cJson := '[ {"description": "methodExamplesDeletePath successfully
executed, parameter received: ' + jPath['user'] + '"} ]'
Endif
/* --------------------------------------------- */
@Delete("examples/class/delete/query/user")
Method methodExamplesDeleteQuery() class classDeleteExamples
Local cJson := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "methodExamplesDeleteQuery successfully
Endif
3.1.2 @GET()
verbo GET. Este método/verbo solicita uma representação do recurso especificado na Uri. Abaixo veremos
exemplos de sua utilização:

/* --------------------------------------- */
@Get("examples/function/get/path/user/:user")
User Function examplesFunctionGetPath()
Local cJson := ""
Local jPath
TOTVSTEC – REST
If (jPath <> Nil)

cJson := '[ { "description": "functionExamplesGetPath successfully
executed, parameter received: ' + jPath['user'] +'"} ]'
Endif
3.1.2.2 Exemplo utilizando função e recebendo parâmetro via query string

/* --------------------------------------- */
@Get("examples/function/get/query/user")
User Function examplesFunctionGetQuery()
Local cJson := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesFunctionGetQuery successfully
Endif
3.1.2.3 Exemplo utilizando classe com métodos recebendo parâmetro via path param e query
string.
Class classGetExamples
Public Method New()

Public Method metodExamplesGetPath()
Public Method metodExamplesGetQuery()
EndClass
Method New() class classGetExamples
Return self
/* --------------------------------------- */
@Get("examples/class/get/path/user/:user")
Method methodExamplesGetPath() class classGetExamples
Local cJson := ""
TOTVSTEC – REST
Local jPath
If (jPath <> Nil)

cJson := '[ {"description": "methodExamplesGetPath successfully
executed, parameter received: ' + jPath['user'] + '"} ]'
Endif
/* --------------------------------------- */
@Get("examples/class/get/query/user")
Method methodExamplesGetQuery() class classGetExamples
Local cJson := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "methodExamplesGetQuery successfully
Endif
3.1.3 @PATCH()
verbo PATCH. Este método/verbo aplica modificações parciais a um recurso. Abaixo veremos exemplos de sua
utilização:

/* ------------------------------------------- */
@Patch("examples/function/patch/path/user/:user")
User Function examplesFunctionPatchPath()
Local cJson := ""
Local jPath
Local cBody := ""
cBody := oRest:getBodyRequest()
If (jPath <> Nil)

cJson := '[ { "description": "examplesFunctionPatchPath successfully
TOTVSTEC – REST
executed, parameter received: ' + jPath['user'] + '" , "body received":"'+ cBody

+ '"} ]'
Endif

/* ------------------------------------------- */
@Patch("examples/function/patch/query/user")
User Function examplesFunctionPatchQuery()
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesFunctionPatchQuery successfully
executed, parameter received: ' + jQuery['user'] + '" , "body received":"'+
cBody + '"} ]'
Endif
string.
Class classPatchExamples
Public Method New()

Public Method methodExamplePatchPath()
Public Method methodExamplePatchQuery()
EndClass
Method New() class classPatchExamples
Return self
/* ------------------------------------------- */
@Patch("examples/class/patch/path/user/:user")
TOTVSTEC – REST
Method methodExamplesPatchPath() class classPatchExamples

Local cJson := ""

Local cBody := ""
Local jPath
If (jPath <> Nil)

cJson := '[ {"description": "examplesMethodPatchPath successfully
+ '"} ]'
Endif
/* ------------------------------------------- */
@Patch("examples/class/patch/query/user")
Method methodExamplesPatchQuery() class classPatchExamples
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesMethodPatchQuery successfully
cBody + '"} ]'
Endif
3.1.4 @POST()
verbo POST. Este método/verbo é utilizado para submeter uma entidade a um recurso específico frequentemente
causando uma mudança no estado do recurso.
Abaixo veremos exemplos de sua utilização:

/* ----------------------------------------- */
@Post("examples/function/post/path/user/:user")
User Function examplesFunctionPostPath()
TOTVSTEC – REST
Local cJson := ""

Local jPath
Local cBody := ""
If (jPath <> Nil)

cJson := '[ { "description": "examplesFunctionPostPath successfully
+ '"} ]'
Endif

/* ----------------------------------------- */
@Post("examples/function/post/query/user")
User Function examplesFunctionPostQuery()
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesFunctionPostQuery successfully
cBody + '"} ]'
Endif
string.
Class classPostExamples
Public Method New()

Public Method methodExamplePostPath()
TOTVSTEC – REST
Public Method methodExamplePosthQuery()

EndClass
Method New() class classPostExamples
Return self
/* ----------------------------------------- */
@Post("examples/class/post/path/user/:user")
Method methodExamplesPostPath() class classPostExamples
Local cJson := ""

Local cBody := ""
Local jPath
If (jPath <> Nil)

cJson := '[ {"description": "examplesMethodPostPath successfully
+ '"} ]'
Endif
/* ----------------------------------------- */
@Post("examples/class/post/query/user")
Method methodExamplesPostQuery() class classPostExamples
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesMethodPostQuery successfully
cBody + '"} ]'
Endif
3.1.5 @PUT()
verbo PUT. Este método/verbo substitui todas as atuais representações do recurso de destino pela carga de dados
da requisição.
Abaixo veremos exemplos de sua utilização:
TOTVSTEC – REST

/* --------------------------------------- */
@Put("examples/function/put/path/user/:user")
User Function examplesFunctionPutPath()
Local cJson := ""
Local jPath
Local cBody := ""
If (jPath <> Nil)

cJson := '[ { "description": "examplesFunctionPutPath successfully
+ '"} ]'
Endif
3.1.5.2 Exemplo utilizando função recebendo parâmetro via query string

/* --------------------------------------- */
@Put("examples/function/put/query/user")
User Function examplesFunctionPutQuery()
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesFunctionPutQuery successfully
cBody + '"} ]'
Endif
TOTVSTEC – REST
string.
Class classPutExamples
Public Method New()

Public Method methodExamplesPutPath()
Public Method methodExamplesPutQuery()
EndClass
Method New() class classPutExamples
Return self
/* --------------------------------------- */
@Put("examples/class/put/path/user/:user")
Method methodExamplesPutPath() class classPutExamples
Local cJson := ""

Local cBody := ""
Local jPath
If (jPath <> Nil)

cJson := '[ {"description": "examplesMethodPutPath successfully
+ '"} ]'
Endif
/* --------------------------------------- */
@Put("examples/class/put/query/user")
Method methodExamplesPutQuery() class classPutExamples
Local cJson := ""
Local cBody := ""
Local jQuery
If (jQuery <> Nil)

cJson := '[ {"description": "examplesMethodPutQuery successfully
cBody + '"} ]'
TOTVSTEC – REST
Endif
3.2 B - Serviços sem uso de @Annotation

A utilização do recurso de @annotations na linguagem TL++ possibilitou a simplificação da escrita para o
desenvolvimento de API´s REST, mas ainda é possível desenvolver aplicações sem utilização deste recurso no
modo tradicional, trataremos disto nesta documentação.
3.2.1 Inicialização de um serviço REST

Para poder utilizar aplicações REST sem o uso das @annotations, obrigatoriamente é necessário criar um serviço
Http por meio de uma função fazendo uso de um objeto JSon. Veremos no exemplo abaixo como fazer isto:
User Function fInitService()
Local oVdrCtrl := VdrCtrl():New()

Local cAppPath := "/examples"
Local nResult := -1
Local jConfig
//Definição das configurações do HttpServer

jConfig['HTTPSERVER'] := JsonObject():New()
jConfig['HTTPSERVER']['Enable'] := .T.
jConfig['HTTPSERVER']['Log'] := .F.
jConfig['HTTPSERVER']['Charset'] := "ISO-8859-1"
jConfig['HTTPSERVER']['Servers'] := {"INIT_HTTP_REST"}

jConfig['INIT_HTTP_REST'] := JsonObject():New()
jConfig['INIT_HTTP_REST']['Port'] := "9995"
jConfig['INIT_HTTP_REST']['HostName'] := "TLPP_REST_SERVER"
jConfig['INIT_HTTP_REST']['ContentTypes'] := "ContentTypes"
jConfig['INIT_HTTP_REST']['Locations'] := {"HTTP_ROOT_01"}
jConfig['HTTP_ROOT_01'] := JsonObject():new()
jConfig['HTTP_ROOT_01']['Path'] := cAppPath
jConfig['HTTP_ROOT_01']['RootPath'] := "C:
\tlppCore\bin\root\web"
jConfig['HTTP_ROOT_01']['DefaultPage'] := {"index.html"}
jConfig['HTTP_ROOT_01']['ThreadPool'] := "INIT_THREAD_POOL_01"
jConfig['INIT_THREAD_POOL_01'] := JsonObject():new()
jConfig['INIT_THREAD_POOL_01']['MinThreads'] := 1
jConfig['INIT_THREAD_POOL_01']['MaxThreads'] := 4
jConfig['INIT_THREAD_POOL_01']['MinFreeThreads'] := 1
jConfig['INIT_THREAD_POOL_01']['GrowthFactor'] := 1
jConfig['INIT_THREAD_POOL_01']['InactiveTimeout'] := 30000
jConfig['INIT_THREAD_POOL_01']['AcceptTimeout'] := 10000

jConfig['INIT_ContentTypes'] := JsonObject():new()
TOTVSTEC – REST
jConfig['INIT_ContentTypes']['htm'] := "text/html"
jConfig['INIT_ContentTypes']['html'] := "text/html"
jConfig['INIT_ContentTypes']['stm'] := "text/html"
jConfig['INIT_ContentTypes']['tsp'] := "text/html"
jConfig['INIT_ContentTypes']['js'] := "text/javascript"
jConfig['INIT_ContentTypes']['json'] := "text/
plain;charset=ISO-8859-1"
jConfig['INIT_ContentTypes']['*'] := "application/octet-
stream"
/* -----------------------------------------------------------
Aqui é feita a chamada para a função responsável por criar o
vinculo entre URN´s e as aplicações
----------------------------------------------------------- */
jConfig['INIT_HTTP_REST']['LoadURNs'] := JsonObject():new()
if !( sLoadURNs(@jConfig['INIT_HTTP_REST']['LoadURNs']) )
return Nil
endif
/*------------------------------------------------------------*/
nResult := oVdrCtrl:Start(jConfig)
if ( ValType(nResult) == 'N' .AND. nResult == 0 )
conout("### Servidor HTTP inicializado com sucesso!")
else
conout("### Erro ao iniciar HTTP Server - retorno [" + cValToChar(nResult) +
"] - " + cValToChar(oVdrCtrl:getControlErrCode()) + " - " + oVdrCtrl:getControl
ErrDesc() )
endif
return nResult
OBS.: Caso já exista algum serviço REST sendo criado por meio de função utilizando-se um JSon, basta incluir a
chamada da static sLoadUrn como será visto no item posterior.
3.2.2 Vinculando a URN à API

Como não está sendo utilizado o recurso das @annotations para poder desenvolver API´s REST, é preciso utilizar
outra forma para efetuar o vínculo com a URN, isto é feito via função. A mesma é chamada do ponto destacado na
função do item anterior, no exemplo citado está sendo feita a chamada para uma função do tipo Static, mas, nada
impede que ela seja do tipo User, desde que respeitando o tipo de retorno e as regras de implementações que serão
vistas no exemplo a seguir:
//Static Function responsável por criar o nó contendo o vínculo entre as URN´s e
as API´s(funções) no objeto jSon que foi recebido como parametro e será
utilizado no serviço REST que será executado a partir das definições do mesmo.
Static Function sLoadURNs(jEndpoints)
Local cDelPath := "/documentation/noannotation/delete"

Local cGetPath := "/documentation/noannotation/get"
TOTVSTEC – REST
Local cPatchPath := "/documentation/noannotation/patch"

Local cPostPath := "/documentation/noannotation/post"

Local cPutPath := "/documentation/noannotation/put"
if(ValType(jEndpoints) == 'U' .Or. ValType(jEndpoints) != 'J')

jEndpoints := jsonObject():New()
endIf

jEndpoints[cGetPath]['GET']['Function'] := "U_getExampleNoAnnotation"
jEndpoints[cGetPath]['GET']['EndPoint'] :={"documentation",
"noannotation", "get"}
jEndpoints[cDelPath]['DELETE'] := JsonObject():new()
jEndpoints[cDelPath]['DELETE']['ClassName'] := ""
jEndpoints[cDelPath]['DELETE']['Function'] := "U_deleteExampleNoAnnotation"
jEndpoints[cDelPath]['DELETE']['EndPoint'] :={"documentation",
"noannotation", "delete"}
jEndpoints[cPatchPath]['PATCH'] := JsonObject():new()
jEndpoints[cPatchPath]['PATCH']['ClassName'] := ""
jEndpoints[cPatchPath]['PATCH']['Function'] := "U_patchExampleNoAnnotation"
jEndpoints[cPatchPath]['PATCH']['EndPoint'] :={"documentation",
"noannotation", "patch"}
jEndpoints[cPostPath]['POST'] := JsonObject():new()
jEndpoints[cPostPath]['POST']['ClassName'] := ""
jEndpoints[cPostPath]['POST']['Function'] := "U_postExampleNoAnnotation"
jEndpoints[cPostPath]['POST']['EndPoint'] :={"documentation",
"noannotation", "post"}
jEndpoints[cPutPath]['PUT'] := JsonObject():new()
jEndpoints[cPutPath]['PUT']['ClassName'] := ""
jEndpoints[cPutPath]['PUT']['Function'] := "U_putExampleNoAnnotation"
jEndpoints[cPutPath]['PUT']['EndPoint'] :={"documentation",
"noannotation", "put"}

Return .T.
3.2.2.1 OBSERVAÇÃO
As funções, os endpoints e as demais configurações utilizadas nos exemplos vistos aqui, devem ser criados
conforme as regras e as necessidades de utilização de cada ambiente e desenvolvedor.
TOTVSTEC – REST
3.3 C - Configuração completa

A partir do release 12.1.279 do AppServer passou a ser disponibilizado também um servidor integrado responsável
pelo REST da linguagem TL++.
Chamamos de Rest Server algumas funcionalidades implementadas no HttpServer especificamente para atender
requisições HTTP no modelo REST utilizando a linguagem TL++.
Para o correto funcionamento do Rest Server é necessário proceder com algumas configurações, a seguir veremos
como fazê-las.
É possível configurar o Rest Server de duas formas: 1.Pelo arquivo de configuração appserver.ini do servidor de
aplicação Appserver. 2.Utilizando um JSON a partir de uma User Function.
Abaixo segue exemplo de configuração com todas as possibilidades.
 Para saber detalhes de cada Sessão / Chave, basta clicar em cima de cada item no exemplo para acessar a
documentação especializada.
...
[HTTPSERVER(see page 59)]

Enable=1
log=0
Servers(see page 63)=HTTP_SSL_SERVER
[HTTP_SSL_SERVER(see page 64)]

hostname=localhost
port=443
Charset(see page 57)=UTF-8
locations(see page 61)=HTTP_ROOT
ContentTypes(see page 58)=ContentTypes
SslCertificate=SSL_certificate.crt
SslCertificateKey=SSL_certificate_key.pem
tlppData(see page 72)='{"Authorization":{"scheme":"basic","OnAuth(see page 194)":"userRestAuthorization"}}'
userData(see page 73)='{"chave":"valor"}'
[HTTP_ROOT(see page 62)]

Path=/
RootPath=root/web
DefaultPage=index.html
AllowMethods=GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS
[THREAD_POOL(see page 69)]

Environment=ENV
UserExits(see page 78)=THREAD_POOL_UEX
MinThreads=1
9 https://tdn.totvs.com/pages/viewpage.action?pageId=505767296
TOTVSTEC – REST
MaxThreads=4
MinFreeThreads=1
GrowthFactor=1
InactiveTimeout=30000
AcceptTimeout=10000
Slaves=SLAVE_01,SLAVE_02
[THREAD_POOL_UEX(see page 80)]

OnStart(see page 85)=userRestEnvironment
OnStop(see page 86)=userRestStop
OnSelect(see page 83)=userRestGrader
OnError(see page 82)=userRestError
[SLAVE_01(see page 67)]

Environment=ENV
UserExits(see page 78)=THREAD_POOL_SLAVES_UEX
MinThreads=1
MaxThreads=2
MinFreeThreads=1
GrowthFactor=1
AcceptTimeout=10000
[SLAVE_02(see page 67)]

Environment=TLPPCORE
UserExits(see page 78)=THREAD_POOL_SLAVES_UEX
MinThreads=2
MaxThreads=4
MinFreeThreads=2
GrowthFactor=1
AcceptTimeout=10000
[THREAD_POOL_SLAVES_UEX(see page 80)]

OnStart(see page 85)=userRestEnvironmentSlave
OnStop(see page 86)=userRestStopSlave
OnSelect(see page 83)=restGraderSlave
OnError(see page 82)=userRestErrorSlave
[ContentTypes(see page 58)]

json = text/plain;charset=UTF-8
xml = text/xml;charset=UTF-8
htm = text/html;charset=UTF-8
html = text/html;charset=UTF-8
txt = text/plain;charset=UTF-8
...
3.3.1 Charset
>>
TOTVSTEC – REST
Charset é a chave para definir com qual Codepage o REST irá trabalhar.
Não é obrigatório informar, porém o REST trabalha com UTF-8 como padrão.
Para mudar conforme necessidade, somente passe o valor desejado na chave Charset da sessão do server criado.
Ex:
Charset=UTF-8
Charset=CP1252
 Configuração
Veja aqui(see page 56) para saber mais sobre como configurar o REST
Importante saber que se o ambiente principal (Environment) estiver com um Codepage diferente do definido no
REST, o application Server converterá automaticamente o buffer de retorno, caso seja um texto, para o Codepage
de saída.
Ex:
Se o Environment estiver configurado com seu Codepage padrão, ou seja CP1252, e o REST também estiver com
seu Codepage padrão(UTF-8), ao final do atendimento da requisição e antes de entregar a mensagem ao cliente,
acontecerá a conversão de CP1252 para UTF-8.
 Erro na conversão entre Codepages
Caso o buffer de origem contenha algum caractere que invalide a conversão entre os Codepages, o
applicationServer informará no console.log
o erro de conversão, conforme exemplo:
[WARN ][SERVER] error in conversion routine. to: utf-8 from: cp1252.
Além disso, o retorno será com o buffer original e não ocorrerá a conversão.
Portanto, no header da mensagem HTTP terá a informação:
Content-Type: charset=cp1252
Ao invés de:
Content-Type: charset=utf-8
3.3.2 ContentTypes (Sessão)

O campo de cabeçalho Content-Type é usado para especificar a natureza dos dados no corpo da mensagem HTTP,
fornece identificadores de tipo e subtipo disponibilizando informações auxiliares que podem ser necessárias para
determinados tipos de retorno.
Após os nomes de tipo e subtipo o restante do campo de cabeçalho é simplesmente um conjunto de parâmetros
especificado em uma notação de atributo / valor(Key/Value).
O conjunto de parâmetros significativos difere entre os tipos, a ordenação dos mesmos não é significativa.
Os seguintes valores são preenchidos automaticamente: "htm=text/html", "html=text/html" e os desconhecidos tem
o valor "application/octet-stream".
A declaração dos mesmos implica na sobreposição dos valores.
TOTVSTEC – REST
3.3.2.1 Exemplos de configuração
Arquivo appserver.ini
[ContentTypes]
htm = text/html
html = text/html
css = text/css
js = text/javascript
json = application/json
txt = text/plain
* = application/octet-stream
JSON
jConfig['INIT_ContentTypes'] := JsonObject():new()
jConfig['INIT_ContentTypes']['htm'] := "text/html"
jConfig['INIT_ContentTypes']['html'] := "text/html"
jConfig['INIT_ContentTypes']['css'] := "text/css"
jConfig['INIT_ContentTypes']['js'] := "text/javascript"
jConfig['INIT_ContentTypes']['json'] := "application/json"
jConfig['INIT_ContentTypes']['txt'] := "text/plain"
jConfig['INIT_ContentTypes']['*'] := "application/octet-stream"
Não há limites para se criar chaves em ContentTypes, o exemplo acima retratou apenas alguns tipos para que a
documentação não fique extensa.
3.3.3 HTTPSERVER (sessão)

Aqui são definidas as configurações básicas para funcionamento do REST Server.
Enable integer/boolean X
Log integer/boolean
Charset string
Servers string/array X
3.3.3.1 Chaves da sessão
Enable
Define se o HttpServer será ativado ao iniciar o Appserver.
TOTVSTEC – REST
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser integer / numérico:
• 0 = disable
• 1 = enable
Caso seja utilizado o JSON seu valor deve ser do tipo boolean / lógico:
• .F. para disable
• .T. para enable
Log
Define se habilita ou não a gravação dos logs de eventos do HttpServer.
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser integer / numérico:
• 0 = disable
• 1 = enable
Caso seja utilizado o JSON seu valor deve ser do tipo boolean / lógico:
• .F. para disable
• .T. para enable
Charset
Documentos de texto transmitidos por HTTP tais como: text/html, text/plain, etc, podem enviar um parâmetro
charset no cabeçalho da requisição para especificar a codificação de caracteres a serem utilizadas no documento. É
muito importante sempre rotular explicitamente documentos Web.
O padrão HTTP 1.1 diz que o charset padrão é o ISO-8859-1. Porém, existem muitos documentos não rotulados em
outras codificações, por isso, quando não se define um charset os navegadores (browsers) podem utilizar uma
codificação de acordo com as suas próprias preferências.
Servers
Lista não vazia com os nomes dos servidores que serão ativados no start do server. Os nomes definidos nesta chave
devem ser utilizados na próxima sessão SERVERS.
Caso seja utilizado o arquivo appserver.ini,o formato do valor desta chave deve ser string com os valores
separados por vírgula. Caso seja utilizado o JSON, seu valor deve ser do tipo array.
3.3.3.2 Exemplos de ativação
[HTTPSERVER]
Enable=1
Log=1
Charset=ISO-8859-1
Servers=INIT_HTTP_REST,INIT_HTTPS_REST
TOTVSTEC – REST
JSON
jConfig['HTTPSERVER']['Servers'] := {"INIT_HTTP_REST","INIT_HTTPS_REST"}
3.3.4 locations (chave)

A chave {locations} é integrante da sessão [SERVERS], e por ela é possível definir um ou mais Paths virtuais para o
mesmo servidor, sendo assim, pode-se informar uma lista, conforme abaixo:
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser string com os nomes de
Locations separados por vírgula.
Caso seja utilizado o JSON, seu valor deve ser do tipo array.
3.3.4.1 Exemplos de configuração - 1 {locations} somente
[INIT_HTTP_REST]
locations=HTTP_ROOT_01
JSON
jConfig['INIT_HTTP_REST']['locations'] := {"HTTP_ROOT_01"}
3.3.4.2 Exemplos de configuração - 2 {locations}
[INIT_HTTP_REST]
locations=HTTP_ROOT_01,HTTP_ROOT_02
JSON
jConfig['INIT_HTTP_REST']['locations'] := {"HTTP_ROOT_01","HTTP_ROOT_02"}
Para saber mais como funcionam os Paths virtuais, acessa a documentação sobre LOCATIONS (Sessão)(see page 62)
TOTVSTEC – REST
3.3.5 LOCATIONS (Sessão)

Através da LOCATIONS conseguimos definir os Paths e agrupamentos de Threads para serviços REST.
Path string X
RootPath string X
DefaultPage string
ThreadPool string X
Path
Path virtual da URL que identificará do serviço.
RootPath
Path físico onde estarão os arquivos manipulados pelo serviço.
DefaultPage
Informa qual será a página estática default do serviço.
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser string.
Pode ser passada uma lista páginas default, com os nomes separados por vírgula.
ThreadPool
Define qual o thread pool irá executar as requisições desta location. O nome definido nesta chave deverá ser
utilizado na sessão THREADPOOL.
TOTVSTEC – REST
[HTTP_ROOT_01]
Path=/rest
RootPath=C:\tlppCore\bin\root\web
DefaultPage=index.html
ThreadPool=INIT_THREAD_POOL_01
[HTTPS_ROOT_01]
Path=/rest
RootPath=C:\tlppCore\bin\root\web
DefaultPage=index.html,totvs.html
ThreadPool=INIT_THREAD_POOL_02
JSON
jConfig['HTTP_ROOT_01'] := JsonObject():new()
jConfig['HTTP_ROOT_01']['Path'] := "/rest"
jConfig['HTTP_ROOT_01']['RootPath'] := "C:\tlppCore\bin\root\web"
jConfig['HTTP_ROOT_01']['DefaultPage'] := {"index.html"}
jConfig['HTTP_ROOT_01']['ThreadPool'] := "INIT_THREAD_POOL_01"
jConfig['HTTPS_ROOT_01'] := JsonObject():new()
jConfig['HTTPS_ROOT_01']['Path'] := "/rest"
jConfig['HTTPS_ROOT_01']['RootPath'] := "C:\tlppCore\bin\root\web"
jConfig['HTTPS_ROOT_01']['DefaultPage'] := {"index.html", "totvs.html"}
jConfig['HTTPS_ROOT_01']['ThreadPool'] := "INIT_THREAD_POOL_02"
3.3.6 servers (chave)

A chave {servers} é integrante da sessão [HTTPSERVER], e por ela é possível definir um ou mais servidores, sendo
assim, pode-se informar uma lista, conforme abaixo:
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser string com os nomes de servers
separados por vírgula.
3.3.6.1 Exemplos de configuração - 1 {servers} somente
[HTTPSERVER]
Servers=INIT_HTTP_REST
TOTVSTEC – REST
JSON
jConfig['HTTPSERVER']['Servers'] := {"INIT_HTTP_REST"}
3.3.6.2 Exemplos de configuração - 2 {servers}
[HTTPSERVER]
Enable=1
Log=1
Charset=ISO-8859-1
Servers=INIT_HTTP_REST,INIT_HTTPS_REST
JSON
jConfig['HTTPSERVER']['Servers'] := {"INIT_HTTP_REST","INIT_HTTPS_REST"}
Para saber mais sobre configuração de servidores, acesse a documentação sobre SERVERS (Sessão)(see page 64)
3.3.7 SERVERS (Sessão)

Define as configurações de cada servidor HTTP e/ou HTTPS informados na sessão [HTTPSERVER] pela chave
{SERVERS}.
Port integer X
Hostname string X
ContentTypes string
Locations string/array X
SslCertificate string
SslCertificateKey string
TOTVSTEC – REST
tlppData string/JSON
userData string/JSON
Port
Define a porta em que o servidor atenderá às requisições após ativado.
Hostname
Define o nome virtual para o servidor ativado.
ContentTypes
Define o nome da sessão que será responsável pela definição dos content-types suportados pelo serviço.
Locations
Define o nome das sessões(locations) deste servidor. O(s) nome(s) definido(s) nesta chave deverão utilizado(s) na
chave LOCATIONS.
Caso seja utilizado o arquivo appserver.ini o formato do valor desta chave deve ser string. Caso seja utilizado o
JSON, seu valor deve ser do tipo array.
SslCertificate
Informar o path com o nome do arquivo do certificado digital, para utilização do REST com o protocolo HTTPS/SSL.
SslCertificateKey
Informar o path com o nome do arquivo com a chave do certificado digital, para utilização do REST com o
protocolo HTTPS/SSL.
tlppData
Esta chave possibilita a configuração simultânea de múltiplos recursos.
TOTVSTEC – REST
O valor informado em tlppData deve ter conteúdo final um JSON válido, e dizemos valor final pois diretamente na
chave você irá colocar um conteúdo de tipo string, que pode ser já o JSON desejado ou o nome de arquivo(*) que
em seu conteúdo seja o JSON.
Caso seja informado o arquivo, pode-se fazer de duas maneiras:
• Nome arquivo (irá buscar o arquivo em rootPath)
• Caminho absoluto + Nome arquivo
Embora no exemplo de configuração dessa documentação essa chave tenha sido usada somente na sessão do
Servidor, ela pode ser usada na sessão de definição das Thread Pool e Slaves.
Atenção -> Esse JSON é de uso exclusivo de recursos nativos do REST, portanto para utilizá-lo é preciso seguir à
risca a documentação de cada funcionalidade.
userData
Esta chave possibilita a configuração simultânea de múltiplos recursos, porém diferente do tlppCore essa é de uso
exclusivo de cada usuário, portanto a utilize para customizar as configurações em seus recursos específicos.
O valor informado em userData deve ter conteúdo final um JSON válido, e dizemos valor final pois diretamente na
chave você irá colocar um conteúdo de tipo string, que pode ser já o JSON desejado ou o nome de arquivo(*) que
em seu conteúdo seja o JSON.
Caso seja informado o arquivo, pode-se fazer de duas maneiras:
• Nome arquivo (irá buscar o arquivo em rootPath)
• Caminho absoluto + Nome arquivo
Embora no exemplo de configuração dessa documentação essa chave tenha sido usada somente na sessão do
Servidor, ela pode ser usada na sessão de definição das Thread Pool e Slaves.
[INIT_HTTP_REST]
Port=9080
Hostname=TLPP_REST_SERVER
ContentTypes=ContentTypes
Locations=HTTP_ROOT_01
tlppdata=c:\config\tlppData.JSON
userdata=c:\config\userData.JSON
[INIT_HTTPS_REST]
Port=9081
Hostname=TLPP_SSL_REST_SERVER
ContentTypes=ContentTypes
Locations=HTTPS_ROOT_01
SslCertificate=totvs_certificate.crt
SslCertificateKey=totvs_certificate_key.pem
tlppdata=c:\config\tlppData.JSON
userdata=c:\config\userData.JSON
TOTVSTEC – REST
JSON
jConfig['INIT_HTTP_REST']['Port'] := "9080"
jConfig['INIT_HTTP_REST']['HostName'] := "TLPP_REST_SERVER"
jConfig['INIT_HTTP_REST']['ContentTypes'] := "ContentTypes"
jConfig['INIT_HTTP_REST']['Locations'] := {"HTTP_ROOT_01"}
jConfig['INIT_HTTP_REST']['tlppdata'] := "c:\config\tlppData.JSON"
jConfig['INIT_HTTP_REST']['userdata'] := "c:\config\userData.JSON"
jConfig['INIT_HTTPS_REST'] := JsonObject():New()
jConfig['INIT_HTTPS_REST']['Port'] := "9081"
jConfig['INIT_HTTPS_REST']['HostName'] := "TLPP_SSL_REST_SERVER"
jConfig['INIT_HTTPS_REST']['Charset'] := "iso-8859-1"
jConfig['INIT_HTTPS_REST']['ContentTypes'] := "ContentTypes"
jConfig['INIT_HTTPS_REST']['Locations'] := {"HTTPS_ROOT_01"}
jConfig['INIT_HTTPS_REST']['SslCertificate'] := "C:
\tlppCore\bin\totvs_certificate.crt"
jConfig['INIT_HTTPS_REST']['SslCertificateKey'] := "C:
\tlppCore\bin\totvs_certificate_key.pem"
jConfig['INIT_HTTPS_REST']['tlppdata'] := "c:\config\tlppData.JSON"
jConfig['INIT_HTTPS_REST']['userdata'] := "c:\config\userData.JSON"
3.3.8 SLAVE (Sessão)

Define as configurações do(s) slave(s) de cada thread pool. As chaves desta sessão são idênticas as da sessão
THREADPOOL, excetuando:
• Slave - deve ser declarada apenas no thread pool pois não é possível configurar mais de um nível de slave
abaixo do thread pool, ou seja, não existe slave de slave.
MaxThreads integer
MinFreeThreads integer
GrowthFactor integer
InactiveTimeout integer
AcceptTimeout integer
TOTVSTEC – REST
Environment
Esta chave só é obrigatória quando utilizada no arquivo appserver.ini, quando utilizado o JSON ela não deve ser
declarada pois como o appserver já se encontra inicializado, ele considera o environment em uso.
MinThreads
MaxThreads
Indica a quantidade máxima de threads ativas no thread pool. O seu valor deve ser maior ou igual ao declarado na
chave "MinThreads".
MinFreeThreads
Indica a quantidade minima de threads ativas no thread pool. Deve ser maior ou igual ao valor declarado na chave
"MinThreads".
GrowthFactor
O fator de crescimeto indica a quantidade de threads novas a serem alocadas sempre que o thread pool estiver com
todas as suas threads em uso. Seu valor deve ser maior que zero.
InactiveTimeout
Indica o tempo em milisegundos que a thread ficará ativa aguardando uma nova requisição. Se este tempo for
expirado a thread poderá ser finalizada conforme controle interno de threads.
O valor informado deve ser maior que zero, mas por ser uma chave opcional, quando não informada o sistema
assume o valor de 30 segundos por default.
AcceptTimeout
Indica o tempo em milisegundos que uma nova requisição deve ficar na fila de processamento aguardando sua vez
de ser atendida. Quando extrapolado este tempo, a requisição é descartada retornando ao client(chamador) o
código de status - 503 - "Server Busy".
TOTVSTEC – REST
UserExits
Indica o nome da sessão com a configuração das chaves UserExits. O(s) nome(s) definido(s) nesta chave deverão ser
utilizado(s) na sessão USEREXITS.
Exemplos de configuração
[SLAVE_THREAD_POOL_01_01]
Environment=HTTPREST
MinThreads=2
MaxThreads=4
MinFreeThreads=2
GrowthFactor=1
AcceptTimeout=10000
UserExits=UE_01
JSON
jConfig['SLAVE_THREAD_POOL_01_01'] := JsonObject():new()
jConfig['SLAVE_THREAD_POOL_01_01']['MinThreads'] := 1
jConfig['SLAVE_THREAD_POOL_01_01']['MaxThreads'] := 4
jConfig['SLAVE_THREAD_POOL_01_01']['MinFreeThreads'] := 1
jConfig['SLAVE_THREAD_POOL_01_01']['GrowthFactor'] := 1
jConfig['SLAVE_THREAD_POOL_01_01']['InactiveTimeout'] := 30000
jConfig['SLAVE_THREAD_POOL_01_01']['AcceptTimeout'] := 10000
jConfig['SLAVE_THREAD_POOL_01_01']['UserExists'] := UE_01
3.3.9 THREADPOOL (Sessão)

Define as configurações do thread pool, o ambiente e as características das threads.
MaxThreads integer X
TOTVSTEC – REST
MinFreeThreads integer X
GrowthFactor integer X
Slaves string/array
InactiveTimeout integer
AcceptTimeout integer
UserExists string
Environment
Esta chave só é obrigatória quando utilizada no arquivo appserver.ini, quando utilizado o JSON ela não deve ser
declarada pois como o appserver já se encontra inicializado, ele considera o environment em uso.
MinThreads
MaxThreads
Indica a quantidade máxima de threads ativas no thread pool. O seu valor deve ser maior ou igual ao declarado na
chave "MinThreads".
MinFreeThreads
Indica a quantidade minima de threads ativas no thread pool. Deve ser maior ou igual ao valor declarado na chave
"MinThreads".
GrowthFactor
O fator de crescimeto indica a quantidade de threads novas a serem alocadas sempre que o thread pool estiver com
todas as suas threads em uso. Seu valor deve ser maior que zero.
TOTVSTEC – REST
Slaves
Lista com o(s) thread pool(s) filho(s)/slave(s) deste thread pool. Pode(m) ser utilizado(s) para que sejam
direcionados os atendimentos das requisições.
Quando declarada, esta chave respeita o formato de string no appserver.ini e o formato de array quando utilizado
o JSON.
InactiveTimeout
Indica o tempo em milisegundos que a thread ficará ativa aguardando uma nova requisição. Se este tempo for
expirado a thread poderá ser finalizada conforme controle interno de threads.
AcceptTimeout
Indica o tempo em milisegundos que uma nova requisição deve ficar na fila de processamento aguardando sua vez
de ser atendida. Quando extrapolado este tempo, a requisição é descartada retornando ao client(chamador) o
código de status - 503 - "Server Busy".
UserExits
Indica o nome da sessão com a configuração das chaves UserExits. O(s) nome(s) definido(s) nesta chave deverão ser
utilizado(s) na sessão USEREXITS.
3.3.9.2 Observações
** Quando declarada, esta chave respeita o formato de string no appserver.ini e o formato de array quando
utilizado o JSON.
Exemplos de configuração
[INIT_THREAD_POOL_01]
MinThreads=2
MaxThreads=4
MinFreeThreads=2
GrowthFactor=1
TOTVSTEC – REST
Slaves=SLAVE_THREAD_POOL_01_01,SLAVE_THREAD_POOL_01_02
AcceptTimeout=10000
UserExits=UE_01
[INIT_THREAD_POOL_02]
MinThreads=1
MaxThreads=5
MinFreeThreads=1
GrowthFactor=1
Slaves=SLAVE_THREAD_POOL_02_01,SLAVE_THREAD_POOL_02_02
UserExits=UE_02
JSON
jConfig['INIT_THREAD_POOL_01']['Slaves'] := {"SLAVE_THREAD_POOL_01_01","SLAVE_TH
READ_POOL_01_02"}
jConfig['INIT_THREAD_POOL_01']['InactiveTimeout'] := 30000
jConfig['INIT_THREAD_POOL_01']['AcceptTimeout'] := 10000
jConfig['INIT_THREAD_POOL_01']['UserExists'] := UE_01
jConfig['INIT_THREAD_POOL_02']['Slaves'] := {"SLAVE_THREAD_POOL_02_01","SLAVE_TH
READ_POOL_02_02"}
jConfig['INIT_THREAD_POOL_02']['UserExists'] := UE_02
3.3.10 tlppData (chave)
3.3.10.1 O que é?
A camada tlppCore do REST server possui uma infinidade de funcionalidades nativas que serão configuradas
através dessa chave.
Nota: As regras para uso dessa chave seguem o mesmo modo de UserData(see page 73), porém não pode-se criar
configurações aleatórias nessa chave, dever-se-á seguir a documentação de cada funcionalidade conforme suas
documentações.
3.3.10.2 Configuração
Observem o exemplo de configuração abaixo:
TOTVSTEC – REST
Nota: os trechos que estão ocultos foram substituídos por ... para facilitar a leitura. A configuração completa você
pode consultar aqui(see page 56)

[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
...
[HTTP_SRV]
locations=HTTP_ROOT
tlppData=''
...
[HTTP_ROOT]
...
[THREAD_POOL]
tlppData=''
...
[SLAVE_01]
tlppData=''
...
[SLAVE_02]
tlppData=''
...
Notem que é possível configurar essa chave desde o nível do server, até o mais especialista dos slaves, porém,
como dito anteriormente, é preciso seguir a documentação à risca de cada documentação para o correto uso
dessas chaves.
Sendo assim, começamos agora a demonstrar como se utiliza a cada um dos Callback.
3.3.10.3 Como se utilizam?

1 - onAuth(see page 194)
3.3.11 userData (chave)
3.3.11.1 O que é?
Uma das preocupações do REST tlppCore é manter uma flexibilidade de uso onde o usuário/cliente possa ter
recursos suficientes para desenvolver seus serviços REST conforme suas necessidades.
Uma dessas flexibilidades é uma chave de configuração de uso exclusivo do desenvolvedor, onde pode informar a
quantidade de conjuntos de {chave:valor} que quiser através de um JSON.
TOTVSTEC – REST
3.3.11.2 Como usar?

O nome da chave deverá ser userData, ela pode ser informada no INI do appserver [detalhes aqui(see page 25)] ou via
JSON, caso opte por executar o REST via código-fonte [detalhes aqui(see page 27)].
O userData deve ao final ser um JSON, porém existem algumas formas de informá-lo ao server, vamos à elas:
JSON diretamente na chave

Exemplo:
userData={"exemplo":"direto na chave"}
Esse modo é o mais simples, pois a informação já estará diretamente na chave.
Porém, valores em chaves podem ter a limitação na quantidade de caracteres do conteúdo do valor dependendo
da versão do appserver utilizada (consulte documentação e versão do server).
Caso necessite utilizar JSON extensos, sugerimos utilizar os modos seguintes:
JSON através de um arquivo

Nesse modo será informado na chave o nome de um arquivo, na qual seu conteúdo será o JSON desejado para a
configuração, vejamos:
Exemplo: (somente nome do arquivo):
userData=userData.json
No exemplo acima, o arquivo deverá estar na mesma pasta do appserver.
Exemplo: (caminho absoluto + nome do arquivo)
userData=c:\configRest\userData.json
O uso de caminho absoluto facilita na manutenção de arquivos de configuração, pois podem estar localizados em
local central.
Notas
1 - A extensão do arquivo não é obrigatória ser .json, pode-se utilizar .txt.
2 - O conteúdo do arquivo deve ser um JSON válido.
TOTVSTEC – REST
3.3.11.3 Onde usar?

Essa chave pode ser usada em diversos níveis da infraestrutura do REST server, tal flexibilidade serve para ser
usada conforme sua necessidade.
Considerando essa informação, pode-se então informar um userData nos seguintes níveis:
Para todos
• Server
Para Thread de atendimento
• Thread Pool
• Slaves
1 - Podem haver configurações coexistentes entre Server e ( Thread Pool ou Slave ).
2 - Não podem haver configurações coexistentes entre Thread Pool e Slave.
3 - Se Thread Pool possuir Slave, a configuração do userData deve ser feito diretamente no Slave.
4 - A userData que estiver configurada no Thread Pool somente será considerada se não possuir Slave.
Devemos lembrar que, quando uma Thread Pool possuir Slaves, o atendimento à requisição de fato será feito pelo
Slave e não pela Thread Pool, embora a requisição passe inicialmente pela Thread Pool, porém somente será usada
para distribuição da requisição para um dos Slaves com base nas regras do [onSelect].
O atendimento será feito pela Thread Pool somente quando ele não possuir Slave configurado.
Observem os exemplos de configuração, feitas no INI, abaixo :
Exemplo 1 (sem Slave)
[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
[HTTP_SRV]
locations=HTTP_ROOT
userData={"config":"server"}
[HTTP_ROOT]
[THREAD_POOL]
userData={"config":"threadpool"}
Nesse caso, temos 2 (dois) userData configurados:
Um para o servidor todo, ou seja, de qualquer Thread teremos acesso a esse mesmo userData.
TOTVSTEC – REST
O outro para as Threads de atendimento, e todas pegarão o userData configurado na Thread Pool, no exemplo
acima com o nome de [THREAD_POOL].
Exemplo 2 (com 2 Slaves)
[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
[HTTP_SRV]
locations=HTTP_ROOT
userData={"config":"server"}
[HTTP_ROOT]
[THREAD_POOL]
[SLAVE_01]
userData={"config":"slave01"}
[SLAVE_02]
userData={"config":"slave02"}
Nesse caso, temos 3 (três) userData configurados:
Um para o servidor todo, ou seja, de qualquer Thread teremos acesso a esse mesmo userData.
Os outros 2 (dois) para as Threads de atendimento, porém, cada uma de seu respectivo Slave, ou seja, se a
requisição for distribuída para qualquer thread do [SLAVE_01], o conteúdo
de userData será {"config":"slave01"}, caso seja distribuída para qualquer thread do [SLAVE_02], então o
conteúdo de userDataserá {"config":"slave02"}
3.3.11.5 Como resgatar os valores de userData

Para obter os valores configurados em userData, temos disponível dois métodos em oRest, são eles:
oRest:getThreadPoolServerUserData()
Esse método retornará o JSON informado no userData da sessão Server, nos exemplos aqui utilizados, a sessão
seria [HTTP_SRV] e seu conteúdo:
{"config":"server"}
Esse método quando requerido, sempre retornará o valor configurado no server, independentemente de qual
Thread está a execução do serviço.
TOTVSTEC – REST
Acesse sua documentação aqui(see page 133)
oRest:getThreadPoolUserData()
Esse método retornará o JSON informado no userData do Thread Pool, ou do Slave.
Conforme dito anteriormente, essa variação ocorre devido à configuração (se existirão slaves) e de qual thread está
atendendo a requisição.
Para ficar claro, vamos utilizar os exemplos acima.
1. Se o cenário for do "Exemplo 1 (sem Slave)", então o método irá retornar o valor informado na sessão
Thread Pool, de nome [THREAD_POOL] e seu conteúdo seria:
{"config":"threadpool"}
1. Se o cenário for do "Exemplo 2 (com 2 Slaves)", então o método irá retornar o valor informado na sessão
Slave da qual pertence a thread que de fato está atendendo a requisição, sendo assim, temos 2
possibilidades:
2 - a) Se a thread pertencer ao primeiro Slave, então a sessão será de nome [SLAVE_01] e seu conteúdo:
{"config":"slave01"}
2 - b) Se a thread pertencer ao segundo Slave, então a sessão será de nome [SLAVE_02] e seu conteúdo:
{"config":"slave02"}
Acesse sua documentação aqui(see page 141)
Nota
O retorno da ambos os métodos será sempre em formato JSON.
Exemplo
No exemplo abaixo, estamos utilizando os dois métodos.
Sugerimos que utiliza o exemplo e modifique a configuração do seu server para que fixe bem o conhecimento sobre
o assunto.
@Get("sample/userData")
function sampleUserData()
TOTVSTEC – REST
local cReturn := ''

local cTmp := ''
local jUserData
jUserData := oRest:getThreadPoolServerUserData()
cTemp := jUserData["config"]
if ( valtype(cTemp) <> 'C' )
cTemp := ''
endif
cReturn += '{"serverUserData":"' + cTemp + '"'
jUserData := oRest:getThreadPoolUserData()
cTemp := jUserData["config"]
if ( valtype(cTemp) <> 'C' )
cTemp := ''
endif
cReturn += ',"threadpoolUserData":"' + cTemp + '"}'
oRest:setResponse( cReturn )
return
3.3.12 UserExits (chave)
3.3.12.1 O que são?

O REST server possui recursos de Callback, definidos na sessão [User Exits], onde é possível configurar funções
customizadas para serem executadas em quatro (4) momentos específicos, sendo:
• dois (2) na infraestrutura do server:
• Criação da Thread [onStart];
• Finalização da Thread [onStop].
• dois (2) no atendimento da requisição HTTP:
• Escolha qual Thread executará a requisição HTTP [onSelect];
• Tratamento dos erros de runtime [onError].
Sendo assim, ao informar o nome da função em uma dessas chaves, o tlppCore irá executar a função do usuário
conforme sua funcionalidade proporcionando flexibilidade no uso do REST.
Nota: Necessário informar um nome válido de função e que esteja compilada no RPO correspondente no
Environment do serviço REST, caso contrário, o tlppCore irá ignorar essa configuração e seguirá sem o desvio do
Callback.
Observem o exemplo de configuração abaixo:
pode consultar aqui(see page 56)
TOTVSTEC – REST
[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
...
[HTTP_SRV]
locations=HTTP_ROOT
...
[HTTP_ROOT]
...
[THREAD_POOL]
UserExits=TP_UEX
...
[TP_UEX]
OnSelect=U_OnSelect
OnError=U_OnError
[SLAVE_01]
UserExits=SLAVES_UEX
...
[SLAVE_02]
UserExits=SLAVES_UEX
...
[SLAVES_UEX]
OnStart=U_OnStart
OnStop=U_OnStop
OnError=U_OnError
Nesse exemplo de configuração, optamos por algo simples, ou seja, deixamos para a Thread principal
[THREAD_POOL] a responsabilidade de escolha das threads de atendimento, por isso configuramos a função de
Select e para as Threads de Slaves a responsabilidade de atendimento das requisições, dessa forma configuramos
para elas as funções de Start e Stop.
Note que o tratamento de erro, função de Error, deixamos configurado para todas as Threads, pois é comum à
todos.
Sendo assim, começamos agora a demonstrar como se utiliza a cada um dos Callback.
3.3.12.3 Como se utilizam?

Para cada User Exits, utilize sua documentação específica:
1 - onStart(see page 85)
2 - onStop(see page 86)
3 - onSelect(see page 83)
TOTVSTEC – REST
4 - onError(see page 82)

3.3.13 UserExits (Sessão)

Define as funções ADVPL/TL++ a serem executadas para determinados eventos com a thread.
OnStart String
OnStop String
OnError String
OnSelect String
OnStart
Função que será executada na inicialização da thread.
OnStop
Função que será executada na finalização da thread.
OnError
Função que será executada caso ocorra algum erro na thread. Pode ser utilizada para tratar error.log, pois recebe o
objeto error como parâmetro permitindo customizar a saída desta informação.
OnSelect
Função que poderá ser executada para para selecionar quem atenderá a requisição.
Mais detalhes sobre User Exits, consulte aqui(see page 78)
[UE_01]
OnStart=ON_START_01
OnStop=ON_STOP_01
OnError=ON_ERROR_01
OnSelect=ON_SELECT_01
TOTVSTEC – REST
[UE_02]
OnStart=ON_START_02
OnStop=ON_STOP_02
OnError=ON_ERROR_02
OnSelect=ON_SELECT_02
JSON
jConfig['UE_01'] := JsonObject():new()
jConfig['UE_01']['OnStart'] := ON_START_01
jConfig['UE_01']['OnStop'] := ON_STOP_01
jConfig['UE_01']['OnError'] := ON_ERROR_01
jConfig['UE_01']['OnSelect'] := ON_SELECT_01
jConfig['UE_02'] := JsonObject():new()
jConfig['UE_02']['OnStart'] := ON_START_02
jConfig['UE_02']['OnStop'] := ON_STOP_02
jConfig['UE_02']['OnError'] := ON_ERROR_02
jConfig['UE_02']['OnSelect'] := ON_SELECT_02
TOTVSTEC – REST
4 3 - Funções de Usuário
O REST permite que o usuário possa customizar o comportamento padrão conforme lhe convenha.
Veja onde é possível customizar:
• Controle de Threads
• onStart (see page 85)
Inicialização da Thread
• onStop(see page 86)

Parada da Thread
• onError(see page 82)

Captura de erros (exception) das Threads
• Atendimento de Requisições
• onSelect(see page 83)
Escolha da qual Slave e/ou Thread irá atender a requisição
• oAuth(see page 194)

Valida a autenticação da requisição ao serviço REST
4.1 onError
Toda execução do REST é protegido pela camada do tlppCore, evitando falta de retorno ou outros efeitos colaterais
quando houver erros de runtime.
Embora haja um tratamento padrão para os erros, é possível customizar esse tratamento através de uma função
configurada através do onStop, sendo assim, o usuário pode por exemplo, enviar por e-mail o erro, gerar eventos
de monitoramento, ou seja, conforme a necessidade de cada um.
4.1.1 Parâmetros
A função customizada de tratamento de erro recebe o objeto oError, para mais detalhes sobre esse objeto, consulte
sua documentação no TDN10.
4.1.2 Retorno
Não há utilidade para retorno algum pois é ignorado, portanto sugerimos que o retorno seja NULL.
4.1.3 Exemplo
function U_onError( oError as object ) as void
local cCodeTrace := U_getCodeTrace() as character

local cFault := '' as character

U_TrataErro( cCodeTrace, oError:genCode, oError:description )
10 https://tdn.totvs.com/display/tec/Classe+ErrorClass
3 - Funções de Usuário – 82
TOTVSTEC – REST
cFault += '{'
cFault += '"code":"' + cCodeTrace + '",'
cFault += '"message":"um erro interno ocorreu, procure o administrador do
sistema"'
cFault += '}'
if ( type('oRest') == 'O' )

oRest:SetFault( cFault )
endif
return Nil
Nesse exemplo, padronizamos o retorno de mensagem com um código de rastro e deixamos para uma função de
Tratamento de erro U_TrataErro(), essa função estaria registrando o erro em local de fácil localização posterior
para que o administrador de sistema tome as devidas providências.
Esse é somente um exemplo do que pode ser feito através desse Callback.
Importante: Caso seja configurado o Callback de OnError e, nem na função configurada, nem momento anterior o
Código de Status ou a Mensagem de retorno tenha sido modificada pela implementação do usuário, a camada
tlppCore irá garantir que o serviço REST retorno o código 500 - Internal Server Error.
4.2 onSelect
Quando configuramos a infraestrutura do REST no INI do appserver, podemos criar diversos Thread Pools, ou seja,
conjuntos de threads disponíveis para o atendimento das requisições HTTP.
Porém, como é decidido qual thread de fato irá atender a requisição HTTP é algo que pode ser modificado. A
camada tlppCore tem seu algoritmo de distribuição das conexões, porém não é o foco desse documento explicar
como funciona, e sim ensinar como modificar esse algoritmo.
Importante ressaltar que ele te servirá não somente para modificar o algoritmo, mas dará o poder de decidir se a
requisição será atendida ou não, se a conexão deve ser encerrada imediatamente e até decidir que a partir de certo
momento, o tlppCore utilize o algoritmo padrão.
Basicamente, essa função tem que retornar o valor do índice correspondente ao Slave para o qual deseja indicar
como responsável pelo atendimento da requisição HTTP.
O índice pode ser encontrado buscando pela lista (array) retornado pelo método oRest:getThreadPoolSlaves(),
ficando a critério de quem implementa o algoritmo de busca e escolha.
Logo mais a baixo, iremos detalhar as demais opções e suas finalidades na sessão de retorno.
4.2.1 Parâmetros
A função customizada recebe 3 (três) parâmetros, sendo:
1 - cClassName
Nome da classe que foi implementada para a execução quando requisitado a "endpoint" correspondente do
serviço REST. (pode estar em branco)
2 - cFunctionName
TOTVSTEC – REST
Nome da função ou do Método que foi implementado para a execução quando requisitado o endpoint
correspondente do serviço REST.

3 - cProgramType
Tipo do programa, sendo:
Valor = 1 - Implementação do endpoint do serviço REST através de endpoint.
Valor = 2 - Implementação do endpoint do serviço através do callback de LoadURN. (descrito em documento
próprio)
Nota: Embora não seja esse o momento de executar cada método ou função, saber quem será executado é
importante, pois pode-se nessa camada implementar a validação de controle sobre autenticação X permissão de
acesso por rotina a ser executada, concedendo mais poder a esse Callback
4.2.2 Retorno
O retorno dessa função deve ser do tipo numérico, indicando o índice correspondente do Slave contido na lista em
oRest:GetThreadPoolSlaves() na qual deseja que a Thread seja responsável pelo atendimento da requisição.
Pode-se retornar as seguintes opções:
• Maior que 0 (zero) >>
Índice do slave para qual deseja transferir a responsabilidade de atendimento.
• -1
Indica que deseja que o algoritmo do tlppCore seja o responsável pela escolha
• -2
Indica que não irá atender a essa requisição, porém deixa que o server responda para o cliente requisitante.
• -3
Derruba a conexão de modo silencioso, sem dar resposta para o cliente requisitante. Ex: útil para quando
detectar tentativa de invasão.
4.2.3 Exemplo
function restGrader( cClassName as character, cFunctionName as character,
cProgramType as character ) as integer
Local nIndex := -1 as integer

local aSlaves := oRest:GetThreadPoolSlaves() as array
local nA := 0 as integer
for na := 1 to len(aSlaves)
if ( aSlaves[nA]:ID == 6 ) // logica qualquer
nIndex := nA
endif
next
return nIndex
TOTVSTEC – REST
4.3 onStart
Ao iniciar qualquer Thread destinada ao funcionamento do REST, existe a possibilidade de executar uma função de
Callback para que o usuário possa tomar ações que julgar necessário na criação da Thread.
Pode-se por ela, desde realizar operações de preparação de ambiente, até decidir que essa determinada Thread
não será iniciada.
4.3.1 Parâmetros
A função customizada não recebe parâmetros, porém é possível obter as informações pertinentes ao REST através
do objeto oRest.
4.3.2 Retorno
O retorno deve ser booleano para que funcione corretamente, e mesmo que a função retorne algo diferente do
exigido a camada tlppCore irá se proteger e converter o retorno para booleano, porém para esses casos sempre irá
considerar o valor como FALSE.
Sendo assim, o comportamento do REST fica:
Tipo Retorno Valor Valor Considerado
boolean true true
boolean false false
nil --- false
string --- false
numeric --- false
date --- false
array --- false
object --- false
Importante ressaltar que, existindo essa função e o valor considerado for FALSE, a Thread não será inicializada e
portanto será encerrada tão logo seja iniciada, não ficando disponível para uso. Logo, é preciso atenção para o
valor de retorno da função.
TOTVSTEC – REST
4.3.3 Exemplo
user function onStart() as logical
local lOK := .T. as logical
// Somente permitirá criar a Thread se conseguir preparar o Ambiente

// a lógica de implementação fica a à critério / necessidade de cada um
lOK := U_preparaAmbiente()
return lOK
4.4 onStop
Essa função é análoga a onStart apesar de ocorrer no momento oposto, afinal a mesma é executada quando há a
finalização da thread independente do motivo, seja por algum erro/solicitação do servidor ou por execução de
algum processo externo. Sabendo-se disso, a função onStop não deve ser utilizada para ocorrências ou erros com
os objetos instanciados na execução das API's.
4.4.1 Parâmetros
A função customizada não recebe parâmetros.
4.4.2 Retorno
O retorno não tem funcionalidade para este Callback, portanto a camada tlppCore irá ignorar qualquer retorno
feito por essa função.
4.4.3 Exemplo
user function onStop() as logical
local lOK := .T. as logical
// a lógica de implementação fica a à critério / necessidade de cada um

lOK := U_fechaAmbiente()
return lOK
Importante: Vale ressaltar que: o onStop é executado quando há finalização da thread ! Não devem ser
considerados para esta função, as informações dos objetos utilizados ao longo da execução da API, afinal
dependendo do momento em que ocorreu a finalização da thread o objeto em questão pode nem ter sido
instanciado. Porém, caso seja necessário obter alguma informação dos objetos criados, recomendamos sempre
proteger o acesso a estrutura dos mesmos.
TOTVSTEC – REST
5 4 - Entendendo o objeto oREST

O objeto oRest é a interface que o desenvolvedor tem para acesso à todas as funcionalidades do REST no servidor.
Para entendê-lo melhor, leia toda essa documentação!
Veja mais em:
• A - O que é oRest?(see page 87)

• B - Resgatando valores da requisição(see page 87)
• C - Definindo as respostas(see page 91)
• D - Todos os métodos(see page 96)
• E - Todas as funções(see page 169)
5.1 A - O que é oRest?

O REST server disponibiliza um objeto para obtenção de dados e manipulação de informação de cada requisição
que é atendida pelo servidor.
Para facilitar o seu uso, todas as funcionalidades foram encapsuladas dentro de uma classe, sendo assim, acessível
através de um objeto.
Tal objeto não precisa ser construído, pois ele é declarado com escopo público e construído na inicialização de
cada Thread e a ele é dado o nome de oRest.
Portanto, para cada Thread de atendimento haverá um objeto oRest para uso.
Para saber os métodos disponíveis para uso, acesse sua documentação técnica aqui(see page 96).
5.2 B - Resgatando valores da requisição

Existem algumas formas de acessar dados enviados para a requisição, são elas:
• Body(see page 87)

• HTTP Header (requisição)(see page 88)
• Path Param(see page 89)
• Query String(see page 90)
5.2.1 Body
Requisições HTTP podem enviar dados através do Body da mensagem e em nosso REST é possível resgatar esse
valor da seguinte forma:
#include "tlpp-core"
#include "tlpp-rest"
@Get("sample/request/body")
user function sampleBody()
local cCode := ''

local cReturn := ""
4 - Entendendo o objeto oREST – 87

TOTVSTEC – REST
local jBody := ''

local cBody := ""
if ( !empty( cBody ) )
cReturn := "Parâmetros capturados: [" + cBody + "]"
// Transforma em JSON

jBody := JsonObject():new()
jBody:fromJson( cBody )
if ( jBody <> Nil )

cCode := jBody:GetJsonText("code")
endif
endif
return
Note que fazemos uso do método oRest:getBodyRequest() para obter o conteúdo enviado por Body.
Esse método nos retorna no formato na qual está encapsulado na mensagem, portanto é preciso tratá-lo conforme
lhe for conveniente.
5.2.2 HTTP Header (requisição)

Requisições HTTP possuem um cabeçalho [Header], um conjunto de chave:valor que servem para determinar
comportamentos esperados da requisição através de chaves e valores definidos em protocolos internacionais.
Porém pode-se também enviar conjuntos de chave:valor que se desejar.
Para resgatar o valor veja o exemplo:
@Get("sample/function/header")
user function sampleHeader()
local cReturn := ""

local jHeader := Nil
jHeader := oRest:getHeaderRequest()
if ( jHeader <> Nil )
cReturn := "Parâmetros capturados: [" + jHeader:ToJSon() + "]"
endif

TOTVSTEC – REST
oRest:SetResponse( cReturn )
return
Para obter todos os dados do Header oRest:getHeaderRequest().

Esse método já nos retorna em formato JSON, portanto, para acessar o dado de um determinado parâmetro, basta
seguir como abaixo:
cCode := jHeader[ 'code' ]
5.2.3 Path Param

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.
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:
@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")

TOTVSTEC – REST
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().
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
5.2.4 Query String

A Query String é um modelo clássico de manutenção do estado da página e são conjuntos de pares/valores
anexados a URL.
Seu uso é simples, após a URL de determinada página, adicionamos o primeiro valor usando a seguinte sintaxe: ?
Chave=Valor.
Para passarmos mais de um conjunto, os mesmos devem ser concatenados usando o caractere coringa &.
Do lado da execução do serviço, resgatamos seus valores da seguinte forma:
@Get("sample/request/querystringexample")
user function sampleQueryString()
local cReturn := ""

local jQueryString := Nil
jQueryString := oRest:getQueryRequest()
if ( jQueryString <> Nil )
cReturn := "Parâmetros capturados: [" + jQueryString:ToJSon() + "]"
endif
oRest:setResponse(cReturn)
return
Note que fazemos uso do método oRest:getQueryRequest() para obter todos os parâmetros enviados via Query
String.
seguir como abaixo:

TOTVSTEC – REST
jQueryString := oRest:getQueryRequest()
cCode := jQueryString[ 'code' ]
Para o exemplo acima funcionar, a chamada deveria ser assim:

http://localhost:8080/sample/request/querystringexample?code=1
ou
http://localhost:8080/sample/request/querystringexample?name=Zack&code=1
5.3 C - Definindo as respostas

Existem algumas formas de acessar dados enviados para a requisição, são elas:
• Corpo da Mensagem(see page 91)

• Formato da Mensagem(see page 93)
• HTTP Header (resposta)(see page 93)
• HTTP Status Code(see page 93)
• Mensagem de erro(see page 95)
5.3.1 Corpo da Mensagem

O corpo da mensagem de retorno é uma das duas principais forma de retornar informação para o requisitante, e é
muito simples de utilizar.
Existem alguns métodos responsáveis para tal finalidade, sendo:
• Específicos para somente a mensagem
• oRest:setResponse()(see page 156)
• oRest:resetMessageResponse()(see page 146)

• Envolve também o código da mensagem
• oRest:setFault() (see page 151)

Alimenta a mensagem de retorno, porém como você está indicando que ocorreu um erro, modifica o
Código de Status do HTTP como 500.
• oRest:resetResponse()(see page 147)

Além de apagar a mensagem setada até o momento, modifica o Código de Status do HTTP para o
status inicial, ou seja, 200.
Abaixo iremos demonstrar o uso de oRest:setResponse() e oRest:resetMessageResponse()
5.3.1.1 Exemplo 1 (simples)


TOTVSTEC – REST
@get("sample/setResponse_1")
user function sampleSetResponse_1()
local cReturn := '{"sample":"1"}'
return
5.3.1.2 Exemplo 2 (resposta segmentada)

local cReturn := ''
oRest:setResponse( '{"sample":"' )
if ( '_2' $ procname() )
oRest:setResponse( '2' )
else
oRest:setResponse( 'unknown' )
endif
oRest:setResponse( '"}' )
return
Note que nesse exemplo, a mensagem foi sendo construída em partes, ou seja, oRest:setResponse() vai
concatenando as mensagens enviadas.
5.3.1.3 Exemplo 3 ("resetando" a resposta)

local cReturn := ''
oRest:setResponse( '{"sample":"0"}' )
// Reseta mensagem

oRest:resetMessageResponse()
oRest:setResponse( '{"sample":"3"}' )
return
Note que nesse exemplo, a mensagem foi supostamente construída errada, porém, para modificar ela por inteiro, é
preciso resetar a mensagem setada até o momento para poder setar com o conteúdo novo.

TOTVSTEC – REST
5.3.2 Formato da Mensagem

É possível modificar o formato da mensagem de retorno conforme convier.
Imaginemos que o conteúdo da sua mensagem seguiu o padrão JSON, porém ao enviar a mensagem ela chegará
como formato texto, sendo assim, o cliente tem que fazer a conversão.
Nesse caso, podemos modificar o formato da mensagem indicando o formato através do Header da resposta
através do método oRest:setKeyHeaderResponse(), veja o exemplo a seguir:
5.3.2.1 Exemplo
@get("sample/setResponse/Json")
user function sampleSetResponseJson()
oRest:setKeyHeaderResponse('Content-Type','application/json')
oRest:setResponse( '{"sample":"format"}' )
return
Mais detalhes sobre o método oRest:setKeyHeaderResponse()(see page 152)
5.3.3 HTTP Header (resposta)

Para a manipulação do Header, existem alguns métodos para facilitar essa tarefa, são eles:
É possível saber mais detalhes de cada método acessando a documentação específica.
• oRest:getHeaderResponse()(see page 111)
• oRest:getKeyHeaderResponse()(see page 112)
• oRest:existKeyHeaderResponse()11
• oRest:setHeaderResponse()(see page 152)
• oRest:setKeyHeaderResponse()(see page 155)
• oRest:appendKeyHeaderResponse()(see page 99)
• oRest:updateKeyHeaderResponse()(see page 158)
• oRest:deleteKeyHeaderResponse()(see page 100)
5.3.4 HTTP Status Code

Requisições HTTP são síncronas, portanto a cada requisição necessitam uma resposta, mesmo que básica para que
o motor que fez a requisição possa tomar decisões.
Uma das informações obrigatórias na resposta é o Status Code do HTTP, pois através somente do código já é
possível tomar algumas ações.
Por exemplo, se receber o código 200, o motor já sabe que a requisição foi feita com sucesso, porém, se receber
500, já saberemos que houve um erro interno no servidor e essa requisição não obteve sucesso na ação desejada.
O REST permite modificar o Status Code do HTTP conforme desejar.
Existem alguns métodos responsáveis para tal finalidade, sendo:
11 https://tdn.totvs.com/display/tec/oRest%3AExistKeyHeaderResponse

TOTVSTEC – REST
• Específicos para somente a mensagem

• oRest:setStatusCode()(see page 157)
• oRest:resetStatusCode()(see page 93)

• Envolve também o código da mensagem
• oRest:setFault()(see page 151)

Alimenta a mensagem de retorno, porém como você está indicando que ocorreu um erro, modifica o
Código de Status do HTTP como 500.
• oRest:resetResponse()(see page 147)

Além de modificar o Código de Status do HTTP para o status inicial, ou seja, 200, apaga a mensagem
setada até o momento.
Abaixo iremos demonstrar o uso de oRest:setStatusCode() e oRest:resetStatusCode()
5.3.4.1 Exemplo 1 (simples)

@get("sample/setStatusCode_1")
user function sampleSetStatusCode_1()
loval cUser := ''

local cReturn := ''
local jQuery
if ( jQuery <> Nil )
cUser := jQuery[ 'user' ]
endif

if ( !empty( cUser ) )
cReturn := '{"user":"' + cUser + '","message":""}'
else
oRest:setStatusCode(400) // Bad Request
cReturn := '{"user":"","message":"invalid user"}'
endif
return
5.3.4.2 Exemplo 2 ("resetando" o status)


TOTVSTEC – REST
@get("sample/setStatusCode_2")
user function sampleSetStatusCode_2()
loval cUser := ''

local cReturn := '{"sample":"1"}'
local jQuery
oRest:setStatusCode(400) // Bad Request

if ( U_validParameters( 'user' ) )
oRest:resetStatusCode()
cReturn := processParameters()
else
cReturn := '{"user":"","message":"invalid user"}'
endif
return
Note que nesse exemplo, antes de validar os parâmetros já setamos o Status Code como 400 e após verificarmos se
todos os parâmetros estão OK, voltamos ao Estado original..
5.3.5 Mensagem de erro

Basicamente, uma mensagem de erro é definida pelo Status Code do HTTP, embora possa ser complementada ou
definida pelo Corpo da Mensagem.
A forma de geração de mensagem de erro é uma preferência pessoal, pois há quem defenda implementações mais
simples e os códigos e controles fiquem todos na mensagem e há quem defenda seguir a risca a obrigatoriedade de
mudar o Status Code do HTTP. Não iremos divagar sobre o assunto nem defender modo algum, apenas iremos
mostrar como implementar de forma simples os modos.
5.3.5.1 Exemplo utilizando a forma mais simples de geração de erro

Nesse exemplo, com o uso de apenas 1 (um) método, já definimos a mensagem e o Status Code.
@get("sample/setFault")
user function samplesetFault()
local cUser := ''

local jQuery
endif
if ( upper(cUser) == 'ADMIN' )

oRest:setResponse( '{"admin":"ok"}' )
else

TOTVSTEC – REST
oRest:setFault( '{"admin":"no"}' )
endif
return
Note que utilizamos o método oRest:setFault, nele definimos a mensagem que gostaríamos de retornar, porém,
automaticamente o REST server já marca o Status Code como 500.
Caso deseje outro Status code, sugerimos utilizar a implementação do segundo exemplo.
Mais detalhes sobre o método oRest:setFault()(see page 151)
5.3.5.2 Exemplo utilizando 2 métodos

Nesse exemplo, faremos uso de 2 (dois) métodos, uma para definimos a mensagem e o outro para o Status Code.
@get("sample/erro/mode_2")
user function sampleErrorMode2()
local cUser := ''

local cReturn := ''
local jQuery
endif
if ( upper(cUser) == 'ADMIN' )

cReturn := '{"admin":"ok"}'
else
oRest:setStatusCode( 403 ) // Forbidden
cReturn := '{"admin":"no"}'
endif
return
Nesse caso, utilizamos um método para modificar o Status Code conforme nossa necessidade, pois 500 (Internal
Server Error) não determina o erro correto, e depois seguimos definindo a mensagem de retorno..
Mais detalhes sobre modificar o Status Code HTTP(see page 93)
5.4 D - Todos os métodos
5.4.1 Namespace
tlpp.rest

TOTVSTEC – REST
5.4.2 Hierarquia
• tObject12
• Rest
5.4.3 Propriedades
Rest:nThreadID13 Rest:URN14
5.4.4 Métodos
• oRest:appendKeyHeaderResponse(see page 99)
• oRest:deleteKeyHeaderResponse(see page 100)
• oRest:existKeyHeaderRequest(see page 101)
• oRest:getBodyRequest(see page 102)
• oRest:getCentryPointAuthorizationOnAuth(see page 103)
• oRest:getCentryPointAuthorizationScheme(see page 104)
• oRest:getCentryPointEnvironment(see page 105)
• oRest:getCentryPointError(see page 105)
• oRest:getCEntryPointExit(see page 106)
• oRest:getCEntryPointGrader(see page 107)
• oRest:getCloseAfterSend(see page 108)
• oRest:getConnectionRequest(see page 109)
• oRest:getHeaderRequest(see page 110)
• oRest:getHeaderResponse(see page 111)
• oRest:getKeyHeaderResponse(see page 112)
• oRest:getLentryPointAuthorization(see page 113)
• oRest:getLEntryPointExit(see page 114)
• oRest:getLEntryPointGrader(see page 115)
• oRest:getMethodRequest(see page 116)
• oRest:getPathParamsRequest(see page 117)
• oRest:getPathRequest(see page 118)
• oRest:getProtocolRequest(see page 118)
• oRest:getQueryRequest(see page 119)
• oRest:getRetCodResponse(see page 120)
• oRest:getRetMsgResponse(see page 121)
• oRest:getStatusResponse(see page 122)
• oRest:getThreadIdRequest(see page 123)
• oRest:getThreadPool_SvcId_TPType(see page 123)
• oRest:getThreadPoolAcceptTimeout(see page 124)
• oRest:getThreadPoolAuthorizationScheme(see page 125)
• oRest:getThreadPoolEnvironment(see page 126)
• oRest:getThreadPoolGrowthFactor(see page 127)
• oRest:getThreadPoolId(see page 128)
• oRest:getThreadPoolInactiveTimeout(see page 129)
• oRest:getThreadPoolMaxThreads(see page 130)
• oRest:getThreadPoolMinFreeThreads(see page 131)
12 //tdn.totvs.com/tObject
13 //tdn.totvs.com/properties%5CnThreadID.md
14 //tdn.totvs.com/properties%5CURN.md

TOTVSTEC – REST
• oRest:getThreadPoolMinThreads(see page 132)

• oRest:getThreadPoolName(see page 133)

• oRest:getThreadPoolServerUserData(see page 133)
• oRest:getThreadPoolServiceId(see page 134)
• oRest:getThreadPoolServiceName(see page 135)
• oRest:getThreadPoolServicePort(see page 136)
• oRest:getThreadPoolServiceSSL(see page 137)
• oRest:getThreadPoolSlaves(see page 138)
• oRest:getThreadPoolStatus(see page 139)
• oRest:getThreadPoolType(see page 140)
• oRest:getThreadPoolUserData(see page 141)
• oRest:getThreadPoolUserExitName(see page 142)
• oRest:getThreadPoolUserExitOnError(see page 143)
• oRest:getThreadPoolUserExitOnSelect(see page 143)
• oRest:getThreadPoolUserExitOnStart(see page 144)
• oRest:getThreadPoolUserExitOnStop(see page 144)
• oRest:httpCallEnd(see page 145)
• oRest:resetMessageResponse(see page 146)
• oRest:resetResponse(see page 147)
• oRest:resetStatusCode(see page 148)
• oRest:sendZipped(see page 149)
• oRest:setCloseAfterSend(see page 150)
• oRest:setFault(see page 151)
• oRest:setHeaderResponse(see page 152)
• oRest:setHttpEnd(see page 154)
• oRest:setKeyHeaderResponse(see page 155)
• oRest:setResponse(see page 156)
• oRest:setStatusCode(see page 157)
• oRest:updateKeyHeaderResponse(see page 158)
• Rest:ExistKeyHeaderResponse(see page 159)
• Rest:getBodyResponse(see page 160)
• Rest:getFullURLRequest(see page 161)
• Rest:getLentryPointEnvironment(see page 162)
• Rest:getLEntryPointError(see page 163)
• Rest:getThreadPoolAuthorizationOnAuth(see page 164)
• Rest:getURLRequest(see page 165)
• Rest:getUserExit(see page 165)
• Rest:getXhrRequest(see page 166)
• Rest:setUserExit(see page 167)
5.4.4.1 Exemplos
User Function UsandoRest()

Return
5.4.4.2 Abrangência
19.0.0.0

TOTVSTEC – REST
5.4.5 oRest:appendKeyHeaderResponse
Adiciona um novo valor a uma chave do cabeçalho de resposta Header ResponseHeaderResponse. Observe que o
valor antigo da chave não é eliminado, o novo valor é concatenado a ele.
5.4.5.1 Sintaxe
appendKeyHeaderResponse( < cKey >, < cValue > )
5.4.5.2 Parâmetros
Nome Tipo Descrição Obrigatório Referência
cKey string Chave cujo valor será alterado X
cValue string Valor que deve ser adicionado X

na chave
5.4.5.3 Retorno
Nome Tipo Descrição
xreturn lógico Indica se a operação foi efetuada com sucesso .T..T..
5.4.5.4 Exemplos
// http://localhost:9090/api/testAppendKeyHeader
@Get("testAppendKeyHeader")
Function u_appendKeyHeaderExample()
Local lRet := .F.
Local cRet := "Append OK - Verifique o Header Response"
if ! oRest:setKeyHeaderResponse("Content-Type", "text/html")
cRet := "Erro ao setar text na chave content-type"
else
if !oRest:appendKeyHeaderResponse("Content-Type","charset=utf-8")
cRet := "Erro ao setar text na chave content-type"
endif
endif
return oRest:setResponse(cRet)

TOTVSTEC – REST
11/2019
5.4.6 oRest:deleteKeyHeaderResponse
Elima uma chave do cabeçalho de resposta Header ResponseHeaderResponse. Observe a RCF sobre 'Response
Header Fields' e veja que alguns campos não podem ser eliminados.
5.4.6.1 Sintaxe
deleteKeyHeaderResponse( < cKey > )
5.4.6.2 Parâmetros
cKey string Nome da chave que será X

eliminada.
5.4.6.3 Retorno
xreturn lógico Se verdadeiro .T..T. indica que o campo foi eliminado

do cabeçalho
5.4.6.4 Exemplos
// http://localhost:9090/api/testDeleteKeyHeader
@Get("testDeleteKeyHeader")
Function u_DeleteKeyHeaderExample()
Local lRet := .F.

Local cRet := 'Chave eliminada.'
if !oRest:getKeyHeaderResponse("Allow")
cRet := "Fail"
endif

TOTVSTEC – REST
11/2019
5.4.7 oRest:existKeyHeaderRequest
Responsável verificar se uma chave existe no header da requisição
5.4.7.1 Sintaxe
existKeyHeaderRequest( < cKey > )
5.4.7.2 Parâmetros
cKey string String que contém a chave para X

ser procurada
5.4.7.3 Retorno
lRet lógico Indica se a chave procurada existe
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/existKeyHeaderRequest
5.4.7.5 Exemplos
@Get("/documentation/existKeyHeaderRequest")
Function u_fExistKeyHeaderRequest()
Local cKey := "Connection"
Local cResponse := ""
Local lRet := .F.
lRet := oRest:existKeyHeaderRequest(cKey)
if (lRet)
cResponse := '{"existKeyHeaderRequest": "Chave ' + cKey + ' existe no
header da requisição' + '"}'
else
cResponse := '{"existKeyHeaderRequest": "Chave ' + cKey + ' não existe

TOTVSTEC – REST
no header ou método existKeyHeaderRequest não foi executado"}'

endif
return oRest:setResponse(cResponse)
01/2020
5.4.8 oRest:getBodyRequest
Responsável por retornar o body da requisição HTTP
5.4.8.1 Sintaxe
oRest:getBodyRequest()
5.4.8.2 Retorno
cBody caractere Conteúdo do Body
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getBodyRequest
5.4.8.4 Exemplos
@Get("/documentation/getBodyRequest")
function u_fGetBodyRequest() as logical
local cBody := oRest:getBodyRequest() as character

local cResp := '' as character
cResp := '{'
cResp += '"getBodyRequest": ' + if( empty(cBody), 'false', 'true' )
cResp += ','
cResp += '"lenght":' + cValToChar( len(cBody) )
cResp += '}'
conout( ' # EndPoint: /documentation/getBodyRequest' )

conout( ' # Body....: ' + cBody )
conout( ' # Response: ' + cResp )
oRest:setKeyHeaderResponse('Content-Type','application/json')

TOTVSTEC – REST
oRest:setResponse( cResp )
return .T.
07/2019
5.4.8.6 versão: 01.02.04
5.4.9 oRest:getCentryPointAuthorizationOnAuth
Para a autenticação Basic, é possível determinar qual função irá fazer a verificação do usuário e senha enviados
pela requisição. Esse método retorna o nome da função configurada.
5.4.9.1 Sintaxe
getCEntryPointAuthorizationOnAuth()
5.4.9.2 Retorno
cEntryPointAuthorizationOnAuth string Retorna o nome da função, de callback,

configurada.
5.4.9.3 Exemplos
@Get("/documentation/getEntryPointAuth")
Function u_getEntryPointAuth()
Local cRet := ""
cRet := oRest:getCEntryPointAuthorizationOnAuth()
if (cRet != "")
conout("O ponto de função para realizar a autenticação para as
requisições HTTP é: " + cRet)
else
conout("Nao foi configurado ponto de função para realizar a autenticação
para as requisições HTTP.")
endif

TOTVSTEC – REST
04/2020
5.4.9.5 Veja também

• getLEntryPointAuthorizationOnAuth
5.4.10 oRest:getCentryPointAuthorizationScheme
Retorna valor da propriedade privada referente ao nome da função do Entry Point
5.4.10.1 Sintaxe
getCentryPointAuthorizationScheme()
5.4.10.2 Retorno
getCentryPointAuthorizationScheme string valor da propriedade
• Para executar o exemplo faça uma chamada get para o endPoint"/documentation/
getCentryPointAuthorizationScheme""/documentation/getCentryPointAuthorizationScheme"
5.4.10.4 Exemplos
@Get("/documentation/getCentryPointAuthorizationScheme")
Function u_getCentryPointAuthorizationScheme()
cResponse := '{"getCentryPointAuthorizationScheme": "método

getCentryPointAuthorizationScheme executado com sucesso, retornando['+ ::getCent
ryPointAuthorizationScheme +']"}'
04/2020

TOTVSTEC – REST
5.4.11 oRest:getCentryPointEnvironment
É possível configurar uma função de callback, para que o usuário realize o processamento que julgar necessário, a
ser executada na criação de uma thread destinada ao REST. Esse método retorna o nome da função configurada.
5.4.11.1 Sintaxe
getCentryPointEnvironment()
5.4.11.2 Retorno
cEntryPointEnvironment string Nome da função de callback, se não houver função

configurada retorna vazio.
5.4.11.3 Exemplos
@Get("/documentation/getEntryPoint")
Function u_getEntryPoint()
Local cRet := ""
cRet := oRest:getCentryPointEnvironment()
if (cRet != "")
conout("O ponto de função para preparação de ambiente é: " + cRet)
else
conout("Nao foi configurado ponto de função para preparação de ambiente")
endif
return
04/2020

• getLentrntryPointEnvironment
5.4.12 oRest:getCentryPointError
É possível configurar uma função de callback, para que o usuário customize o tratamento de erros. Esse método
retorna o nome da função configurada.

TOTVSTEC – REST
5.4.12.1 Sintaxe
getCentryPointError()
5.4.12.2 Retorno

5.4.12.3 Exemplos
@Get("/documentation/getEntryPointError")
Function u_getEntryPointError()
Local cRet := ""
cRet := oRest:getCentryPointError()
if (cRet != "")
conout("O ponto de função para realizar o tratamento de erros é: " +
cRet)
else
conout("Nao foi configurado ponto de função para tratamento de erros.")
endif
04/2020

• getLEntryPointError(see page 105)
5.4.13 oRest:getCEntryPointExit
Quando ocorre a finalização de uma thread de atendimento REST, uma função de callback pode ser chamada para
que o usuário realize o processamento que julgar necessário. sse método retorna o nome da função configurada.
5.4.13.1 Sintaxe
getCEntryPointExit()

TOTVSTEC – REST
5.4.13.2 Retorno
cEntryPointExit string Retorna o nome da função, de callback, configurada. Se

retornar vazio é porque não foi realizada a configuração.
5.4.13.3 Exemplos
@Get("/documentation/getEntryPointExit")
Function u_getEntryPointExit()
Local cRet := ""
cRet := oRest:getCentryPointExit()
if (cRet != "")
conout("O ponto de função para realizar tratamento na finalização da
thread é: " + cRet)
else
conout("Nao foi configurado ponto de função para tratamento na
finalização da thread.")
endif
04/2020

• getLEntryPointExit
5.4.14 oRest:getCEntryPointGrader
Retorna valor da propriedade privada referente ao nome da função do Entry Point
5.4.14.1 Sintaxe
getCEntryPointGrader()

TOTVSTEC – REST
5.4.14.2 Retorno

5.4.14.3 Exemplos
@Get("/documentation/getEntryPointGrader")
Function u_getEntryPointGrader()
Local cRet := ""
cRet := oRest:getCEntryPointGrader()
if (cRet != "")
conout("O ponto de função para realizar o balanceamento de threads é: "
+ cRet)
else
conout("Nao foi configurado ponto de função para balanceamento de
threadas.")
endif
04/2020

• getLEntryPointGrader
5.4.15 oRest:getCloseAfterSend
Responsável por retornar o valor de definição para o encerramento da sessão após a requisição
5.4.15.1 Sintaxe
getCloseAfterSend()

TOTVSTEC – REST
5.4.15.2 Retorno
lRet lógico indica o valor definido
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getCloseAfterSend
5.4.15.4 Exemplos
@Get("/documentation/getCloseAfterSend")
Function u_fGetCloseAfterSend()
Local lRet := .F.
lRet := oRest:getCloseAfterSend()
cResponse := '{"getCloseAfterSend": "Neste momento, deve ser .F.: ' +
cValToChar(lRet) + '"}'
06/2020
5.4.16 oRest:getConnectionRequest
Responsável por retornar a conexão utilizada na requisição
5.4.16.1 Sintaxe
getConnectionRequest()
5.4.16.2 Retorno
nConnection número inteiro valor da conexão utilizada na requisição

TOTVSTEC – REST
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getConnectionRequest
5.4.16.4 Exemplos
@Get("/documentation/getConnectionRequest")
Function u_fGetConnectionRequest()
Local nConnection := ""
nConnection := oRest:getConnectionRequest()
if (valtype(nConnection) == 'N')
cResponse := '{"getConnectionRequest": "' + cValToChar(oRest:getConnecti
onRequest()) + '"}'
else
cResponse := '{"getConnectionRequest": "método getConnectionRequest não
foi executado"}'
endif
01/2020
5.4.17 oRest:getHeaderRequest
Responsável por retornar o header da requisição
5.4.17.1 Sintaxe
getHeaderRequest()
5.4.17.2 Retorno
jHeader JsonObject Objeto JSON que contém o header da requisição
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getHeaderRequest

TOTVSTEC – REST
5.4.17.4 Exemplos
@Get("/documentation/getHeaderRequest")
Function u_fGetHeaderRequest()
Local jHeader
if (valtype(jHeader) == 'J')
cResponse := '{"Header":['
cResponse += jHeader:toJson()
cResponse += ']}'
else
cResponse := '{"getHeaderRequest": "método getHeaderRequest não foi
executado"}'
endif
10/2019
5.4.18 oRest:getHeaderResponse
Retorna o Header Response da requisição
5.4.18.1 Sintaxe
getHeaderResponse()
5.4.18.2 Retorno
Retorna JsonObject um objeto do tipo jSon com o conteúdo do Header

Response da requisição
• Para visualizar este exemplo, execute seu serviço rest com a URI: /documentation/getHeaderResponse

TOTVSTEC – REST
5.4.18.4 Exemplos
@Get("/documentation/getHeaderResponse")
Function u_fgetHeaderResponse()
jResp := oRest:getHeaderResponse()
if jResp <> Nil

cResponse := '{"fgetHeaderResponse": "método getHeaderResponse executado
com sucesso", "Header Response Content":"' + jResp:toJSon() + '"}'
endif
return cResponse
11/2019
5.4.19 oRest:getKeyHeaderResponse
Retorna o valor de uma chave do Header do objeto Response da requisição
5.4.19.1 Sintaxe
getKeyHeaderResponse( < cKey >, < cValue > )
5.4.19.2 Parâmetros
cKey string Chave cujo valor deve ser obtido X
cValue string Variável passada por referência que X

conterá o valor chave requisitada
5.4.19.3 Retorno
xreturn lógico Indica se a operação foi efetuada(.T.) ou se não foi

executada(.F.)

TOTVSTEC – REST
• Para visualizar o exemplo, execute o rest no endereço :"/documentation/getKeyHeaderResponse"
5.4.19.5 Exemplos
@Get("/documentation/getKeyHeaderResponse")
Function u_fgetKeyHeaderResponse()
Local lRet := .F.
Local cRet := ''
lRet := oRest:getKeyHeaderResponse("Content-Type", @cRet)

if lRet == .F. .or. valtype(cRet) <> "C" .or. cRet == NIL
cRet := ''
endif
return oRest:setResponse('[ {"description": "fgetKeyHeaderResponse executed: ' +
cRet + '"} ]')
11/2019
5.4.20 oRest:getLentryPointAuthorization
Para a autenticação Basic, é possível determinar qual função irá fazer a verificação do usuário e senha enviados
pela requisição. Esse método indica se essa configuração foi realizada ou não.
5.4.20.1 Sintaxe
getLentryPointAuthorization()
5.4.20.2 Retorno
lEntryPointEnvironment lógico Retorna verdadeiro se houver um callback

configurado, e falso caso contrário.
5.4.20.3 Exemplos
@Get("/documentation/existEntryPointAuth")

TOTVSTEC – REST
Function u_existEntryPointAuth()
Local lRet := .F.
lRet := oRest:getLentryPointAuthorization()
if (lRet)
conout("Foi configurado um ponto de função para realizar a autenticação
para as requisições HTTP: " + oRest:getCentryPointAuthorizationOnAuth())
else
conout("Nao foi configurado ponto de função para realizar a autenticação
para as requisições HTTP.")
endif
return oRest:setResponse(lRet)
04/2020

• getCentryPointAuthorizationOnAuth
5.4.21 oRest:getLEntryPointExit
Quando ocorre a finalização de uma thread de atendimento REST, uma função de callback pode ser chamada para
que o usuário realize o processamento que julgar necessário. Esse método informa se essa função foi ou não
configurada.
5.4.21.1 Sintaxe
getLEntryPointExit()
5.4.21.2 Retorno

5.4.21.3 Exemplos
@Get("/documentation/existEntryPointExit")
Function u_existEntryPointExit()
Local lRet := .F.

TOTVSTEC – REST
lRet := oRest:getLEntryPointExit()
if (lRet)
conout("Foi configurado um ponto de função para finalização da thread: "
+ oRest:getCEntryPointExit())
else
conout("Nao foi configurado ponto de função para finalização da thread.")
endif
04/2020

• getCEntryPointExit
5.4.22 oRest:getLEntryPointGrader
Retorna valor da propriedade privada referente se existe Entry Point
5.4.22.1 Sintaxe
getLEntryPointGrader()
5.4.22.2 Retorno
lEntryPointGrader lógico Valor da propriedade
5.4.22.3 Exemplos
@Get("/documentation/existEntryPointGrader")
Function u_existEntryPointGrader()
Local lRet := .F.
lRet := oRest:getLEntryPointGrader()
if (lRet)
conout("Foi configurado um ponto de função para o balanceamento de
threads: " + oRest:getCentryPointGrader())
else
conout("Nao foi configurado ponto de função o balanceamento de threads")
endif

TOTVSTEC – REST
04/2020

• getCentryPointGrader
5.4.23 oRest:getMethodRequest
Retorna qual o método executado para acessar o endpoint
5.4.23.1 Sintaxe
getMethodRequest()
5.4.23.2 Retorno
cmethod string API método Ex: GET, POST, PUT,

etcEx:GET,POST,PUT,etc
5.4.23.3 Exemplos
// http:localhost:9090/api/minhaURL
@Get("minhaURL")
Function u_getMethodExample()
Local creturn := ""
creturn := oRest:getMethodRequest()
conout(cReturn) // Vai exibir GET
creturn := "{'Method':" + creturn + "}"
oRest:SetResponse(cReturn)
Return
07/2019

TOTVSTEC – REST
5.4.24 oRest:getPathParamsRequest
Responsável por retornar os parâmetros informados na requisição via URI (path param)
5.4.24.1 Sintaxe
getPathParamsRequest()
5.4.24.2 Retorno
jParams JsonObject objeto json com parametros path

parampathparam da requisição
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getPathParamsRequest/
TOTVS
5.4.24.4 Exemplos
@Get("/documentation/getPathParamsRequest/:cKey")
Function u_fGetPathParamsRequest()
local cResponse := ""
local cRet := ""
local jParams := JsonObject():New()
jParams := oRest:getPathParamsRequest()
cRet := jParams['cKey']
if (valtype(cRet) == 'C')
cResponse := '{"getPathParamsRequest":"' + cValToChar(cRet) + '"}' //cRet
vai ter valor igual a "TOTVS"
else
cResponse := '{"getPathParamsRequest": "metodo getPathParamsRequest nao
foi executado"}'
endif
07/2019

TOTVSTEC – REST
5.4.25 oRest:getPathRequest
return the path address of requisition
5.4.25.1 Sintaxe
getPathRequest()
5.4.25.2 Retorno
cPathRequest string The path address of requisition
5.4.25.3 Exemplos
// http:localhost:9090/api/mypath/teste
@Get("mypath/teste")
Function u_getPathExample()
Local creturn := ""
creturn := oRest:getPathRequest()
conout(cReturn) // Vai exibir a URN da requisição, por exemplo
http:localhost:9090/api/mypath/teste
creturn := "{'Path':" + creturn + "}"
Return
01/2020
5.4.26 oRest:getProtocolRequest
Getter para o protocolo de comunicação utilizado na requisição.
5.4.26.1 Sintaxe
getProtocolRequest()

TOTVSTEC – REST
5.4.26.2 Retorno
cProtocol string Protocolo utilizado. Poderá ser HTTP, HTTPS, etc.
5.4.26.3 Exemplos
// http:localhost:9090/api/protocolo
@Get("protocolo")
Function u_getProtocolExample()
Local creturn := ""
creturn := oRest:getMethodRequest()
conout(cReturn) // Vai exibir o protocolo utilizado a requisição, por
exemplo HTTP
creturn := "{'Protocol':" + creturn + "}"
Return
01/2020
5.4.27 oRest:getQueryRequest
Responsável por retornar os parâmetros informados na requisição via URI (query param)
5.4.27.1 Sintaxe
getQueryRequest()
5.4.27.2 Retorno
jParams JsonObject objeto json com parametros query

paramqueryparam da requisição
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getQueryRequest/user?
user=TOTVS

TOTVSTEC – REST
5.4.27.4 Exemplos
@Get("/documentation/getQueryRequest/user")
Function u_fGetQueryRequest()
local cRet := ""
local jParams := JsonObject():New()
jParams := oRest:getQueryRequest()
cRet := jParams['user']
cResponse := '{"getQueryRequest":"' + cValToChar(cRet) + '"}'
else
cResponse := '{"getQueryRequest": "metodo getQueryRequest nao foi
executado"}'
endif
07/2019
5.4.28 oRest:getRetCodResponse
Responsável por retornar o código de status do HTTP contido no objeto oRest
5.4.28.1 Sintaxe
getRetCodResponse()
5.4.28.2 Retorno
nCodeHttpSrv numérico código de status do HTTP utilizado na resposta
• Aconselhamos sempre utilizar o método getStatusResponse() para consulta do valor que será retornado.
Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getRetCodResponse

TOTVSTEC – REST
5.4.28.4 Exemplos
@Get("/documentation/getRetCodResponse")
Function u_fGetRetCodResponse()
local nRet := -1
nRet := oRest:getRetCodResponse()
if (valtype(nRet) == 'N' .and. nRet >= 0)
cResponse := '{"getRetCodResponse":"' + cValToChar(nRet) + '"}'
else
cResponse := '{"getRetCodResponse": "método getRetCodResponse não foi
executado"}'
endif
01/2020
5.4.29 oRest:getRetMsgResponse
Responsável por retornar a mensagem do HTTP contido no objeto oRest
5.4.29.1 Sintaxe
getRetMsgResponse()
5.4.29.2 Retorno
cMessage string mensagem do HTTP utilizado na resposta
• Aconselhamos sempre utilizar o método getBodyResponse() para consulta do valor que será retornado.
Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getRetMsgResponse
5.4.29.4 Exemplos

TOTVSTEC – REST
@Get("/documentation/getRetMsgResponse")
Function u_fGetRetMsgResponse()
local cRet := ""
cRet := oRest:getRetMsgResponse()
cResponse := '{"getRetMsgResponse":"' + cValToChar(cRet) + '"}'
else
cResponse := '{"getRetMsgResponse": "método getRetMsgResponse não foi
executado"}'
endif
01/2020
5.4.30 oRest:getStatusResponse
Retorna o código de status do HTTP que será considerado no retorno da requisição até o momento da pesquisa.
5.4.30.1 Sintaxe
getStatusResponse()
5.4.30.2 Retorno
nCodeHttp numérico código de status do HTTP usado na resposta
• Esse código está guardado na camada tlppCore e só será enviado a camada do appserver no momento de
efetivar a resposta ao requisitante.
5.4.30.4 Exemplos
nCodeHttp := oRest:getStatusResponse()
07/2019

TOTVSTEC – REST
5.4.31 oRest:getThreadIdRequest
Responsável por retornar o ID da thread da requisição
5.4.31.1 Sintaxe
getThreadIdRequest()
5.4.31.2 Retorno
nConnection número inteiro ID da thread da requisição
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadIdRequest
5.4.31.4 Exemplos
@Get("/documentation/getThreadIdRequest")
Function u_fGetThreadIdRequest()
Local nConnection := ""
nConnection := oRest:getThreadIdRequest()
if (valtype(nConnection) == 'N')
cResponse := '{"getThreadIdRequest": "' + cValToChar(oRest:getThreadIdRe
quest()) + '"}'
else
cResponse := '{"getThreadIdRequest": "método getThreadIdRequest não foi
executado"}'
endif
01/2020
5.4.32 oRest:getThreadPool_SvcId_TPType
Retorna o identificador do serviço e qual é o tipo do threadpool que recebeu a requisição

TOTVSTEC – REST
5.4.32.1 Sintaxe
getThreadPool_SvcId_TPType()
5.4.32.2 Retorno
cRet string Retorna o identificador do serviço e qual é o tipo do

threadpool
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/
getThreadPool_SvcId_TPType
5.4.32.4 Exemplos
@Get('/documentation/getThreadPool_SvcId_TPType')
function u_fGetThreadPool_SvcId_TPType()
local cRet := oRest:getThreadPool_SvcId_TPType()
cResponse := '{"getThreadPool_SvcId_TPType":"' + "As informacoes do
threadpool " + oRest:getThreadPoolName() + " sao: " + cRet + '"}'
else
cResponse := '{"getThreadPool_SvcId_TPType": "metodo
getThreadPool_SvcId_TPType nao foi executado"}'
endif
01/2020
5.4.33 oRest:getThreadPoolAcceptTimeout
Responsável por retornar o tempo limite para aceitar (accept timeout) configurada para o threadpool que recebe a
requisição
5.4.33.1 Sintaxe
getThreadPoolAcceptTimeout()

TOTVSTEC – REST
5.4.33.2 Retorno
Accept numérico Timeout configurado para o timeout (em

milissegundos)
getThreadPoolAcceptTimeout
5.4.33.4 Exemplos
@Get('/documentation/getThreadPoolAcceptTimeout')
function u_fGetThreadPoolAcceptTimeout()
local nQtd := oRest:getThreadPoolAcceptTimeout()
if (valtype(nQtd) == 'N')
cResponse := '{"getThreadPoolAcceptTimeout":"' + cValToChar(nQtd) + " eh
accept timeout configurado para o threadpool " + oRest:getThreadPoolName() +
'"}'
else
cResponse := '{"getThreadPoolAcceptTimeout": "metodo
getThreadPoolAcceptTimeout nao foi executado"}'
endif
01/2020
5.4.34 oRest:getThreadPoolAuthorizationScheme
Retorna qual é o tipo de autenticação que o serviço usará.
5.4.34.1 Sintaxe
getThreadPoolAuthorizationScheme()

TOTVSTEC – REST
5.4.34.2 Retorno
cRet string Tipo de autenticação.
5.4.34.3 Exemplos
@Get('/documentation/getThreadPoolAuthorizationScheme')
Function u_authorizationType()
Local cRet := oRest:getThreadPoolAuthorizationScheme()
conout("O usuáro deve implementar as regras de autenticação do tipo " + cRet)
return
05/2020
5.4.35 oRest:getThreadPoolEnvironment
Responsável por retornar em qual ambiente (environment) o threadpool que recebeu a requisição está configurado
5.4.35.1 Sintaxe
getThreadPoolEnvironment()
5.4.35.2 Retorno
cEnvironment string Nome do ambiente que o threadpool está

configurado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolEnvironment

TOTVSTEC – REST
5.4.35.4 Exemplos
@Get('/documentation/getThreadPoolEnvironment')
function u_fGetThreadPoolEnvironment()
local cRet := oRest:getThreadPoolEnvironment()
cResponse := '{"getThreadPoolEnvironment":"' + cRet + " eh environment
(ambiente) que o threadpool " + oRest:getThreadPoolName() + " esta configurado"
+ '"}'
else
cResponse := '{"getThreadPoolEnvironment": "metodo
getThreadPoolEnvironment nao foi executado"}'
endif
01/2020
5.4.36 oRest:getThreadPoolGrowthFactor
Responsável por retornar o fator de crescimento da thread no threadpool que recebeu a requisição
5.4.36.1 Sintaxe
getThreadPoolGrowthFactor()
5.4.36.2 Retorno
Número numérico que indica o fator de crescimento das threads
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolGrowthFactor
5.4.36.4 Exemplos

TOTVSTEC – REST
@Get('/documentation/getThreadPoolGrowthFactor')
function u_fGetThreadPoolGrowthFactor()
local nRet := oRest:getThreadPoolGrowthFactor()
if (valtype(nRet) == 'N')
cResponse := '{"getThreadPoolGrowthFactor":"' + cValToChar(nRet) + " eh
growth factor (fator de crescimento das threads) configurado para o threadpool "
+ oRest:getThreadPoolName() + "}'
else
cResponse := '{"getThreadPoolGrowthFactor": "metodo
getThreadPoolGrowthFactor nao foi executado"}'
endif
01/2020
5.4.37 oRest:getThreadPoolId
Retorna o identificador do threadpool que recebeu a requisição
5.4.37.1 Sintaxe
getThreadPoolId()
5.4.37.2 Retorno
nId numérico Identificador único para o threadpool
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolId
5.4.37.4 Exemplos
@Get('/documentation/getThreadPoolId')
function u_fGetThreadPoolId()
local nRet := oRest:getThreadPoolId()

TOTVSTEC – REST
cResponse := '{"getThreadPoolId":"' + "O ID do threadpool " + oRest:getThrea
dPoolName() + " eh: " + cValToChar(nRet) + '"}'
else
cResponse := '{"getThreadPoolId": "metodo getThreadPoolId nao foi
executado"}'
endif
01/2020
5.4.38 oRest:getThreadPoolInactiveTimeout
Responsável por retornar o tempo limite de inatividade configurada para o threadpool que recebe a requisição
5.4.38.1 Sintaxe
getThreadPoolInactiveTimeout()
5.4.38.2 Retorno
Tempo numérico limite de inatividade configurado (em milissegundos)
getThreadPoolInactiveTimeout
5.4.38.4 Exemplos
@Get('/documentation/getThreadPoolInactiveTimeout')
function u_fGetThreadPoolInactiveTimeout()
local nRet := oRest:getThreadPoolInactiveTimeout()
cResponse := '{"getThreadPoolAcceptTimeout":"' + cValToChar(nRet) + " eh
accept timeout configurado para o threadpool " + oRest:getThreadPoolName() +
'"}'
else

TOTVSTEC – REST
cResponse := '{"getThreadPoolInactiveTimeout": "metodo

getThreadPoolInactiveTimeout nao foi executado"}'
endif
01/2020
5.4.39 oRest:getThreadPoolMaxThreads
Responsável por retornar a quantidade máxima de threads que poderão ficar no ar para o threadpool que recebe a
requisição
5.4.39.1 Sintaxe
getThreadPoolMaxThreads()
5.4.39.2 Retorno
nThreads numérico Quantidade máxima de threads
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolMaxThreads
5.4.39.4 Exemplos
@Get('/documentation/getThreadPoolMaxThreads')
function u_fGetThreadPoolMaxThreads()
local nQtd := oRest:getThreadPoolMaxThreads()
cResponse := '{"getThreadPoolMaxThreads":"' + cValToChar(nQtd) + " eh o
numero maximo de threads que atendem o threadpool " + oRest:getThreadPoolName()
+ '"}'
else
cResponse := '{"getThreadPoolMaxThreads": "metodo getThreadPoolMaxThreads
nao foi executado"}'
endif

TOTVSTEC – REST
01/2020
5.4.40 oRest:getThreadPoolMinFreeThreads
Responsável por retornar o número mínimo de threads que devem ficar disponíveis configurado no threadpool que
recebeu a requisição
5.4.40.1 Sintaxe
getThreadPoolMinFreeThreads()
5.4.40.2 Retorno
Número numérico mínimo de threads que devem ficar disponíveis
getThreadPoolMinFreeThreads
5.4.40.4 Exemplos
@Get('/documentation/getThreadPoolMinFreeThreads')
function u_fGetThreadPoolMinFreeThreads()
local nRet := oRest:getThreadPoolMinFreeThreads()
cResponse := '{"getThreadPoolMinFreeThreads":"' + cValToChar(nRet) + " eh o
numero minimo de threads que esta configurado para ficarem disponiveis no
threadpool " + oRest:getThreadPoolName() + '"}'
else
cResponse := '{"getThreadPoolMinFreeThreads": "metodo
getThreadPoolMinFreeThreads nao foi executado"}'
endif
01/2020

TOTVSTEC – REST
5.4.41 oRest:getThreadPoolMinThreads
Responsável por retornar a quantidade mínima de threads que ficarão no ar para o threadpool que recebe a
requisição
5.4.41.1 Sintaxe
getThreadPoolMinThreads()
5.4.41.2 Retorno
nThreads numérico Quantidade mínima de threads
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolMinThreads
5.4.41.4 Exemplos
@Get('/documentation/getThreadPoolMinThreads')
function u_fGetThreadPoolMinThreads()
local nQtd := oRest:getThreadPoolMinThreads()
cResponse := '{"getThreadPoolMinThreads":"' + cValToChar(nQtd) + " eh o
numero minimo de threads que atendem o threadpool " + oRest:getThreadPoolName()
+ '"}'
else
cResponse := '{"getThreadPoolMinThreads": "metodo getThreadPoolMinThreads
endif
01/2020

TOTVSTEC – REST
5.4.42 oRest:getThreadPoolName
Retorna o nome da ThreadPool que recebeu a requisição, que corresponde a configuração na sessão [ThreadPool]
do arquivo de configuração do AppServer para o serviço REST em uso
5.4.42.1 Sintaxe
getThreadPoolName()
5.4.42.2 Retorno
cTPname string Nome da ThreadPool
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolName
5.4.42.4 Exemplos
@Get('/documentation/getThreadPoolName')
function u_fGetThreadPoolName()
local cRet := oRest:getThreadPoolName()
cResponse := '{"getThreadPoolName":"' + "Nome do threadpool: " + cRet + '"}'
else
cResponse := '{"getThreadPoolName": "metodo getThreadPoolName nao foi
executado"}'
endif
01/2020
5.4.43 oRest:getThreadPoolServerUserData
Responsável por retornar a configuração exclusiva do desenvolver parametrizada no seu serviço rest

TOTVSTEC – REST
5.4.43.1 Sintaxe
getThreadPoolServerUserData()
5.4.43.2 Retorno
jRet JsonObject Objeto JSON com a configuração realizada pelo usuário
getThreadPoolServerUserData Se o retorno for igual a "{}", significa essa configuração não foi definida.
5.4.43.4 Exemplos
@Get("/documentation/getThreadPoolServerUserData")
Function u_fGetThreadPoolServerUserData()
local jRet
jRet := oRest:getThreadPoolServerUserData()
if (valtype(jRet) == 'J')
cResponse := '{"getThreadPoolServerUserData":"' + jRet:toJSON() + '"}'
else
cResponse := '{"getThreadPoolServerUserData": "metodo
getThreadPoolServerUserData nao foi executado"}'
endif
05/2020
5.4.44 oRest:getThreadPoolServiceId
Ao configurarmos o HTTPServer informamos quais servidores seráo ativados. E para cada servidor, definimos uma
lista especificando qual(is) thread pool poderá(ão) executar as requisições REST que chegarem para esse servidor.
O método getThreadPoolServiceId() retorna o identificador (id) do servidor para o qual o thread pool corrente está
processando.

TOTVSTEC – REST
5.4.44.1 Sintaxe
getThreadPoolServiceId()
5.4.44.2 Retorno
nServiceId numérico Identificador do servidor.
5.4.44.3 Exemplos
@Get('/documentation/getThreadPoolServiceId')
Function u_GetServiceId()
Local nRet := oRest:getThreadPoolServiceId()
Conout(" O Id do serviço do threadpool " + oRest:getThreadPoolName() + " é "

+ cValToChar(nRet))
Return
01/2020
5.4.45 oRest:getThreadPoolServiceName
O método getThreadPoolServiceName() retorna o nome do servidor para o qual o thread pool corrente está
processando. Esse nome foi informado na configuração do serviço, seja via arquivo de inicialização do AppServer
(.ini) ou por uma função TLPP (inicializa o HTTP server passando um json como parâmetro).
5.4.45.1 Sintaxe
getThreadPoolServiceName()
5.4.45.2 Retorno
cServiceName string Nome do serviço

TOTVSTEC – REST
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolServiceName
5.4.45.4 Exemplos
@Get("/documentation/getThreadPoolServiceName")
Function u_fGetThreadPoolServiceName()
local cRet := ""
cRet := oRest:getThreadPoolServiceName()
cResponse := '{"getThreadPoolServiceName":"' + cValToChar(cRet) + '"}'
else
cResponse := '{"getThreadPoolServiceName": "metodo
getThreadPoolServiceName nao foi executado"}'
endif
01/2020
5.4.46 oRest:getThreadPoolServicePort
O método getThreadPoolServicePort() retorna o porta do serviço para o qual o thread pool corrente está
processando. Essa porta foi informado na configuração do serviço, seja via arquivo de inicialização do AppServer
(.ini) ou por uma função TLPP (inicializa o HTTP server passando um json como parâmetro).
5.4.46.1 Sintaxe
getThreadPoolServicePort()
5.4.46.2 Retorno
nServicePort numérico Porta na qual o serviço é acessado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolServiceName

TOTVSTEC – REST
5.4.46.4 Exemplos
@Get("/documentation/getThreadPoolServicePort")
Function u_fGetThreadPoolServicePort()
local nRet := -1
nRet := oRest:getThreadPoolServicePort()
if (valtype(nRet) == 'N' .and. nRet >= 0)
cResponse := '{"getThreadPoolServicePort":"' + cValToChar(nRet) + '"}'
else
cResponse := '{"getThreadPoolServicePort": "metodo
getThreadPoolServicePort nao foi executado"}'
endif
01/2020
5.4.47 oRest:getThreadPoolServiceSSL
O método getThreadPoolServiceSSL() retorna se o serviço para o qual o thread pool corrente está processando
utiliza o protocolo de segurança SSL.
5.4.47.1 Sintaxe
getThreadPoolServiceSSL()
5.4.47.2 Retorno
lRet lógico Retorna verdadeiro se o serviço utiliza o protocolo SSL. Falso,

caso contrário
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolServiceSSL
5.4.47.4 Exemplos

TOTVSTEC – REST
@Get("/documentation/getThreadPoolServiceSSL")
Function u_fGetThreadPoolServiceSSL()
local lRet := oRest:getThreadPoolServiceSSL()
if (valtype(lRet) == 'L')
cResponse := '{"getThreadPoolServiceSSL":"' + cValToChar(lRet) + '"}'
else
cResponse := '{"getThreadPoolServiceSSL": "metodo getThreadPoolServiceSSL
endif
01/2020
5.4.48 oRest:getThreadPoolSlaves
Método responsável por retornar os slaves parametrizados para o threadpool que recebeu a requisição
5.4.48.1 Sintaxe
getThreadPoolSlaves()
5.4.48.2 Retorno
aSlaves vetor Retorna um array com os slaves configurados para o

threadpool requisitado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolSlaves
5.4.48.4 Exemplos
@Get("/documentation/getThreadPoolSlaves")
Function u_fGetThreadPoolSlaves()
local aSlaves
local nIndex := 0

TOTVSTEC – REST
local nLenSlaves := -1
aSlaves := oRest:getThreadPoolSlaves()
nLenSlaves := len(aSlaves)
if (valtype(aSlaves) == 'A')
if (nLenSlaves > 0)
cResponse := '{'
cResponse += '{"ThreadPool":"' + oRest:getThreadPoolName() + '"}'
cResponse += ',{"Total Slaves":"' + cValToChar(nLenSlaves) + '"}'
for nIndex := 0 to nLenSlaves

cResponse += ',{"getThreadPoolSlaves":"' + cValToChar(aSlaves[nIndex]:id)
+ '"}'
next
cResponse := '}'
else
cResponse := '{"getThreadPoolSlaves": "nao existem slaves configurados
para o threadpool: ' + oRest:getThreadPoolName() + ' "}'
endif
else
cResponse := '{"getThreadPoolSlaves": "metodo getThreadPoolSlaves nao foi
executado"}'
endif
10/2019
5.4.49 oRest:getThreadPoolStatus
Responsável por retornar o status do threadpool que recebeu a requisição
5.4.49.1 Sintaxe
getThreadPoolStatus()
5.4.49.2 Retorno
nStatus numérico Retorna qual é o estado do thread pool 0 - STOPPED ,

1 - STARTING, 2 - STARTED, 3 -
STOPPING0−STOPPED,1−STARTING,2−STARTED,3−ST
OPPING

TOTVSTEC – REST
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolStatus
5.4.49.4 Exemplos
@Get('/documentation/getThreadPoolStatus')
function u_fGetThreadPoolStatus()
local aStatus := {"STOPPED","STARTING","STARTED","STOPPING"}
local nRet := oRest:getThreadPoolStatus()
cResponse := '{"getThreadPoolStatus":"O status do threadpool ' + oRest:getTh
readPoolName() + " eh: " + cValToChar(nRet) + "(" + aStatus[nRet] + ")" + '"}'
else
cResponse := '{"getThreadPoolStatus": "metodo getThreadPoolStatus nao foi
executado"}'
endif
01/2020
5.4.50 oRest:getThreadPoolType
Responsável por retornar qual é o tipo do threadpool que recebeu a requisição. Os retornos possíveis são 'Slave' ou
'Master'
5.4.50.1 Sintaxe
getThreadPoolType()
5.4.50.2 Retorno
cThreadPoolType string Nome do tipo do threadpool
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolType

TOTVSTEC – REST
5.4.50.4 Exemplos
@Get('/documentation/getThreadPoolType')
function u_fGetThreadPoolType()
local cRet := oRest:getThreadPoolType()
cResponse := '{"getThreadPoolType":"' + cRet + " eh tipo do threadpool " +
oRest:getThreadPoolName() + " esta configurado" + '"}'
else
cResponse := '{"getThreadPoolType": "metodo getThreadPoolType nao foi
executado"}'
endif
01/2020
5.4.51 oRest:getThreadPoolUserData
Responsável por retornar a configuração exclusiva do desenvolver parametrizada no threadpool do seu serviço rest
5.4.51.1 Sintaxe
getThreadPoolUserData()
5.4.51.2 Retorno
jRet JsonObject Objeto JSON com a configuração realizada pelo usuário
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/getThreadPoolUserData Se o
retorno for igual a "{}", significa essa configuração não foi definida.
5.4.51.4 Exemplos

TOTVSTEC – REST
@Get("/documentation/getThreadPoolUserData")
Function u_fGetThreadPoolUserData()
local jRet
jRet := oRest:getThreadPoolUserData()
cResponse := '{"getThreadPoolUserData":"' + jRet:toJSON() + '"}'
else
cResponse := '{"getThreadPoolUserData": "metodo getThreadPoolUserData nao
foi executado"}'
endif
05/2020
5.4.52 oRest:getThreadPoolUserExitName
Retorna o valor da chave [UserExits] configurada na Thread Pool ou na Thread Slave. O conteúdo desse valor,
significa o nome da sessão que deverá existir na INI ou Json de Init do Rest Server onde será possível configurar
todas as funções de usuários disponíveis para modificar funcionalidades padronizadas do REST.
5.4.52.1 Sintaxe
getThreadPoolUserExitName()
5.4.52.2 Retorno
cSrvName string valor de UserExits
5.4.52.3 Exemplos
cUsrName := oRest:getThreadPoolUserExitName()
01/2020

TOTVSTEC – REST
5.4.53 oRest:getThreadPoolUserExitOnError
Retorna o valor da chave [OnError] configurada na sessão definida em [UserExits]. O conteúdo desse valor,
significa o nome da função que será executada no momento que houver um error.log e o tlppCore desviará para
que essa função faça o tratamento de erro, enviando via parâmetro a classe de erro.
5.4.53.1 Sintaxe
getThreadPoolUserExitOnError()
5.4.53.2 Retorno
cFuncError string Nome da funcao de usuário para tratamento de erro
5.4.53.3 Exemplos
cFuncError := oRest:getThreadPoolUserExitOnError()
01/2020
5.4.54 oRest:getThreadPoolUserExitOnSelect
Retorna o valor da chave [OnSelect] configurada na sessão definida em [UserExits]. O conteúdo desse valor,
significa o nome da função que será executada no momento que o servidor REST receber uma nova requisição e
decidir para qual Thread irá encaminhar o processamento.
5.4.54.1 Sintaxe
getThreadPoolUserExitOnSelect()
5.4.54.2 Retorno
cFuncSelect string Nome da função de usuário para escolha de Threads

de atendimento
5.4.54.3 Exemplos
cFuncSelect := oRest:getThreadPoolUserExitOnSelect()

TOTVSTEC – REST
01/2020
5.4.55 oRest:getThreadPoolUserExitOnStart
Retorna o valor da chave [OnStart] configurada na sessão definida em [UserExits]. O conteúdo desse valor,
significa o nome da função que será executada no momento que as Threads do serviço REST estiverem
inicializando.
5.4.55.1 Sintaxe
getThreadPoolUserExitOnStart()
5.4.55.2 Retorno
cFuncStart string Nome da função de usuário para execução na

inicialização da Thread.
5.4.55.3 Exemplos
cFuncStart := oRest:getThreadPoolUserExitOnStart()
01/2020
5.4.56 oRest:getThreadPoolUserExitOnStop
Retorna o valor da chave [OnStop] configurada na sessão definida em [UserExits]. O conteúdo desse valor, significa
o nome da função que será executada no momento que as Threads do serviço REST estiverem finalizando.
5.4.56.1 Sintaxe
getThreadPoolUserExitOnStop()
5.4.56.2 Retorno
cFuncStop string Nome da função de usuário para execução na

finalização da Thread.

TOTVSTEC – REST
5.4.56.3 Exemplos
cFuncStop := oRest:getThreadPoolUserExitOnStop()
01/2020
5.4.57 oRest:httpCallEnd
Restaura atributos que controlam o processamento da requisição. Ess método é executado ao final de cada
requisição.
5.4.57.1 Sintaxe
httpCallEnd()
5.4.57.2 Retorno
lRet lógico Apenas indica se o método foi executado com êxito.
• Utilize esse método se for codificar uma função de callback para tratamento de exceções. O exemplo
exposto aqui é ilustrativo, veja a configuração de tratamento de erro.
5.4.57.4 Exemplos
Function u_errorRecover()
if (oRest != Nil )
oRest:setStatusCode(nStatusCode)
oRest:setFault("Erro interno capturado pela função de callback de erro do
usuário.")
oRest:httpCallEnd()
endif
Return .T.
11/2019

TOTVSTEC – REST

• getThreadPoolUserExitOnError
5.4.58 oRest:resetMessageResponse
Responsável por restaurar o valor padrão da resposta para uma string vazia, independente do momento em que
seja utilizado.
5.4.58.1 Sintaxe
resetMessageResponse()
5.4.58.2 Retorno
lRet lógico indica se o método foi executado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/resetMessageResponse
5.4.58.4 Exemplos
@Get("/documentation/resetMessageResponse")
Function u_fResetMessageResponse()
Local lRet := .F.
lRet := oRest:resetMessageResponse()
if (lRet)
cResponse := '{"resetMessageResponse":"método resetMessageResponse
executado com sucesso"}"
else
cResponse := '{"resetMessageResponse":"Nao foi possivel executar o
método resetMessageResponse"}'
endif
11/2019

TOTVSTEC – REST
5.4.59 oRest:resetResponse
Responsável por restaurar o valor padrão do código de status 200200 e da mensagem de resposta para uma string
vazia, independente do momento em que seja utilizado.
5.4.59.1 Sintaxe
resetResponse()
5.4.59.2 Retorno
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/resetResponse
5.4.59.4 Exemplos
@Get("/documentation/resetResponse")
Function u_fResetResponse()
Local lRet := .F.
lRet := oRest:resetResponse()
if (lRet)
cResponse := '{"resetResponse":"método resetResponse executado com
sucesso"}"
else
cResponse := '{"resetResponse":"Nao foi possivel executar o método
resetResponse"}'
endif
11/2019

TOTVSTEC – REST
5.4.60 oRest:resetStatusCode
Responsável por restaurar os valores padrões para o Status Code (do servidor e do usuário), independente do
momento em que seja utilizado.
5.4.60.1 Sintaxe
resetStatusCode()
5.4.60.2 Retorno
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/resetStatusCode
5.4.60.4 Exemplos
@Get("/documentation/resetStatusCode")
Function u_fResetStatusCode()
Local lRet := .F.
cResponse := '['
lRet := oRest:setStatusCode(400)
if (lRet)
cResponse += '{"setStatusCode":"método setStatusCode executado com
sucesso"}'
else
cResponse += '{"setStatusCode":"Nao foi possivel executar o método
setStatusCode"}'
endif
lRet := oRest:resetResponse()
if (lRet)
cResponse += ',{"resetStatusCode":"método resetResponse executado com
sucesso"}"
else
cResponse += ',{"resetStatusCode":"Nao foi possivel executar o método
resetStatusCode"}'
endif

TOTVSTEC – REST
cResponse += ']'
11/2019
5.4.61 oRest:sendZipped
Responsável definir que o conteúdo seria enviado compactado ("zipado")
5.4.61.1 Sintaxe
sendZipped( < cKey > )
cKey vetor Array que contém o(s) X

modo(s) do zip
5.4.61.3 Retorno
lRet lógico Indica se o método foi executado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/sendZipped e /
documentation/sendZippedCompress
5.4.61.5 Exemplos
//Exemplo 1
@Get("/documentation/sendZipped")
Function u_fSendZippedGzip()
Local aZipped := {}
Local lRet := .F.

TOTVSTEC – REST
Aadd(aZipped, "GZIP")
lRet := oRest:sendZipped(aZipped)
if (lRet)
cResponse := '{"sendZipped": "método sendZipped executado com sucesso"}'
else
cResponse := '{"sendZipped": "método sendZipped nao foi executado"}'
endif
//Exemplo 2
@Get("/documentation/sendZippedCompress")
Function u_fSendZippedCompress()
Local aZipped := {}
Local lRet := .F.
Aadd(aZipped, "COMPRESS")
lRet := oRest:sendZipped(aZipped)
if (lRet)
cResponse := '{"sendZipped": "método sendZipped executado com sucesso"}'
else
cResponse := '{"sendZipped": "método sendZipped nao foi executado"}'
endif
02/2020
5.4.62 oRest:setCloseAfterSend
Responsável por definir o encerramento da sessão após a requisição
5.4.62.1 Sintaxe
setCloseAfterSend( < lSet > )
lSet lógico indica se define ou não o X

encerramento da sessão após a
requisição

TOTVSTEC – REST
5.4.62.3 Retorno
• Para visualizar o exemplo, prepare a requisição com o 'Connection' do header definido como "keep-alive" e
execute seu serviço rest com a URI: /documentation/setCloseAfterSend
5.4.62.5 Exemplos
@Get("/documentation/setCloseAfterSend")
Function u_fSetCloseAfterSend()
Local lRet := ""
cResponse := '{"setCloseAfterSend": "método setCloseAfterSend executado com

sucesso, forçado o encerramento para header keep-alive"}'
lRet := oRest:setCloseAfterSend(.T.)
06/2020
5.4.63 oRest:setFault
Responsável por customizar a mensagem de retorno padrão do servidor rest, ou seja, é possível determinar qual
será a resposta final da requisição em relação a resposta original.
5.4.63.1 Sintaxe
setFault( < cMessage > )
cMessage string Mensagem para ser retornada na X

resposta da requisição

TOTVSTEC – REST
5.4.63.3 Retorno
lRet lógico indica se o metodo foi executado
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/setFault
5.4.63.5 Exemplos
@Get("/documentation/setFault")
Function u_fSetFault()
Local lRet := ""
cResponse := '{"setFault": "método setFault executado com sucesso, mensagem

de retorno padrao alterada"}'
lRet := oRest:setFault(cResponse)
return .T.
12/2019
5.4.64 oRest:setHeaderResponse
5.4.64.1 Rest:setHeaderResponse
Responsável por definir o cabeçalho de resposta. É um cabeçalho HTTP utilizado para fornecer um contexto mais
detalhado da resposta.
Sintaxe
setHeaderResponse( < jValue > )

TOTVSTEC – REST
Parâmetros
jValue JsonObject Objeto JSON contendo os X

cabeçalhos de resposta, cada
chave:valor desse objeto será
definido no cabeçalho da resposta
HTTP
Retorno
cReturn string uma string com o texto do cabeçalho definido.
Observações
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/setHeaderResponse
Exemplos
@Get("/documentation/setHeaderResponse")
Function u_fSetHeaderResponse()
local cJson := '{"Content-Encoding":"gzip","Content-Type":"text/html;
charset=utf-8","Content-Length":"300"}'
local jHeaders
local jRet
local uRet := .F.
jHeaders := JsonObject():New()
uRet := jHeaders:fromJson(cJson)
if (valtype(uRet) == 'U')
jRet := oRest:setHeaderResponse(jHeaders)
cResponse := '{"setHeaderResponse":"' + jRet:toJson() + '"}'
else
cResponse := '{"setHeaderResponse": "metodo setHeaderResponse nao foi
executado"}'
endif
else
cResponse := '{"setHeaderResponse": "metodo setHeaderResponse nao executado
devido a problema com JSON"}'
endif

TOTVSTEC – REST
Abrangência
11/2019
5.4.65 oRest:setHttpEnd
Responsável indicar um encerramento forçado da thread
5.4.65.1 Sintaxe
setHttpEnd()
5.4.65.2 Retorno
lRet lógico Indica o método executou com sucesso
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/setHttpEnd
5.4.65.4 Exemplos
@Get("/documentation/setHttpEnd")
Function u_fsetHttpEnd()
Local lRet := .F.
lRet := oRest:setHttpEnd()
if (lRet)
cResponse := '{"setHttpEnd": "método setHttpEnd executado com sucesso"}'
else
cResponse := '{"setHttpEnd": "O método setHttpEnd não foi executado"}'
endif
11/2019

TOTVSTEC – REST
5.4.66 oRest:setKeyHeaderResponse
Define o valor de uma chave do cabeçalho de resposta
5.4.66.1 Sintaxe
setKeyHeaderResponse( < cKey >, < cValue > )
cKey string Nome da chave cujo valor será X

informado
cValue string Valor chave que está sendo X

definida
5.4.66.3 Retorno
xreturn lógico Indica se a operação foi efetuada com sucesso .T..T. .
5.4.66.4 Exemplos
// http://localhost:9090/api/testSetKeyHeaderRespose
@Get("testSetKeyHeaderRespose")
Function u_setKeyHeaderResponseExample()
Local lRet := .F.

Local cRet := "Erro. Nao foi possivel atualizar a chave"
lRet := oRest:setKeyHeaderResponse("Content-Type", "text")

if lRet
cRet := "Chave atualizada com sucesso"
endif
11/2019

TOTVSTEC – REST
5.4.67 oRest:setResponse
Responsável por inserir o conteúdo do corpo da mensagem na resposta da requisição HTTP. É possível executar
mais de uma vez esse método, mas é importante saber que, a cada execução o conteúdo recebido no parâmetro
será concatenado.
5.4.67.1 Sintaxe
setResponse( [ cMessage ] )
cMessage qualquer Mensagem a ser concatenada no

corpo da mensagem de resposta.
5.4.67.3 Retorno
lRet lógico Indica que o método foi executado.
• *Este parâmetro pode ser de qualquer tipo, caso seja recebido algum valor diferente de nulo/nil o mesmo
será enviado respeitando os tipos permitidos nas regras de resposta de requisições HTTP. Caso não seja
recebido nada ou um valor nulo, não será inserido nada na resposta da requisição. Para visualizar o
exemplo, execute seu serviço rest com a URI: /documentation/setResponse
5.4.67.5 Exemplos
@Get("/documentation/setResponse")
function u_fSetResponse()
local lRet := ""
cResponse := '{"setResponse": "metodo setResponse executado com sucesso"}'


TOTVSTEC – REST
07/2019
5.4.68 oRest:setStatusCode
Responsável por customizar o código de retorno padrão do servidor rest, ou seja, é possível determinar qual será o
status da resposta final da requisição em relação a resposta original.
5.4.68.1 Sintaxe
setStatusCode( < nCode > )
nCode numérico Código para ser retornado no X

status requisição
5.4.68.3 Retorno
• Para visualizar o exemplo, execute seu serviço rest com a URI: /documentation/setStatusCode
5.4.68.5 Exemplos
@Get("/documentation/setStatusCode")
Function u_fSetStatusCode()
Local lRet := ""
lRet := oRest:setStatusCode(350)
if (lRet)
cResponse := '{"setStatusCode": "método setStatusCode executado com
sucesso"}'
else

TOTVSTEC – REST
cResponse := '{"setStatusCode": "Não foi possível executar o método

setStatusCode"}'
endif
08/2019
5.4.69 oRest:updateKeyHeaderResponse
Permite que o usuário dê manutenção em um valor de determinada chave do cabeçalho de repsosta (Header
Response).
5.4.69.1 Sintaxe
updateKeyHeaderResponse( < cKey >, < cValue > )
cKey string Chave cujo valor será X

alterado
cValue string Valor da chave X
5.4.69.3 Retorno
xreturn lógico Indica se a operação foi efetuada(.T.) com sucesso
5.4.69.4 Exemplos
// http://localhost:9090/api/testUpdateKeyHeader
@Get("testUpdateKeyHeader")
Function u_UpdateKeyHeaderExample()
Local lRet := .F.
Local cRet := 'Update realizado com sucesso'
lRet := oRest:updateKeyHeaderResponse("Content-Type", 26)

TOTVSTEC – REST
if !lRet
cRet := "Fail"
endif
11/2019
5.4.70 Rest:ExistKeyHeaderResponse
Verifica se uma determinada chave, recebida por parâmetro, existe no header do objeto response
5.4.70.1 Sintaxe
ExistKeyHeaderResponse( < cKey > )
cKey string Chave a ser procurada X
5.4.70.3 Retorno
lreturn lógico Retona true se a chave procurada existir no header, e false

caso nao exista
• Para visualizar seu exemplo, execute o REST no seguinte endereço:
5.4.70.5 Exemplos

TOTVSTEC – REST
@Get("/documentation/existkeyheaderresponse")
Function u_fexistKeyHeaderResponse()
Local lreturn := .f.
Local cKey := "Content-Type"
lreturn := oRest:existKeyHeaderResponse( cKey )
return oRest:setResponse('{"existKeyHeaderResponse":"' + cValToChar(lReturn) +

'"}')
01/2020
5.4.71 Rest:getBodyResponse
Retorna o Body do ultimo objeto response enviado
5.4.71.1 Sintaxe
getBodyResponse()
5.4.71.2 Retorno
cResponse string Retorna o conteudo do corpobodybody da ultima

resposta enviada
• Para visualizar o exemplo, execute o est no endereço :"/documentation/getBodyResponse"
5.4.71.4 Exemplos

TOTVSTEC – REST
@Get("/documentation/getBodyResponse")
Function u_fgetBodyResponse()
oRest:setResponse( 'test_getBodyResponse' )
cResponse := oRest:getBodyResponse()
oRest:resetResponse()
return oRest:setResponse('{"getBodyResponse":"' + cValToChar(cResponse) + '"}')
07/2019
5.4.72 Rest:getFullURLRequest
Retorna a URL da requisição corrente. Esquema ou protocolo://dominio:porta/caminho/recurso15
5.4.72.1 Sintaxe
getFullURLRequest()
5.4.72.2 Retorno
cURL string URL utilizada na requisição
5.4.72.3 Exemplos
// http://localhost:9090/api/minhaURL
@Get("/documentation/getFullURLRequest")
Function u_fGetFullURLRequest()
Local creturn := ""
creturn := oRest:getFullURLRequest()
creturn := "{'URL':" + creturn + "}"
15 protocolo://dominioporta

TOTVSTEC – REST
conout(cReturn) // Vai exibir http://127.0.0.1:9090/api/minhaURL

Return
11/2019
5.4.73 Rest:getLentryPointEnvironment
É possível configurar uma função de callback, para que o usuário realize o processamento que julgar necessário, a
ser executada na criação de uma thread destinada ao REST. Esse método retorna um valor verdadeiro caso esse
ponto tenha sido configurado, e falso caso contrário.
5.4.73.1 Sintaxe
getLentryPointEnvironment()
5.4.73.2 Retorno

5.4.73.3 Exemplos
@Get("/documentation/existEntryPoint")
Function u_existEntryPoint()
Local lRet := .F.
lRet := oRest:getLentryPointEnvironment()
if (lRet)
conout("Foi configurado um ponto de função para preparação de ambiente:
" + oRest:getCentryPointEnvironment())
else
conout("Nao foi configurado ponto de função para preparação de ambiente")

TOTVSTEC – REST
endif
04/2020

• getCentryPointEnvironment(see page 162)
5.4.74 Rest:getLEntryPointError
É possível configurar uma função de callback, para que o usuário customize o tratamento de erros. Esse método
retorna um valor verdadeiro caso esse ponto tenha sido configurado, e falso caso contrário.
5.4.74.1 Sintaxe
getLEntryPointError()
5.4.74.2 Retorno

5.4.74.3 Exemplos
@Get("/documentation/existEntryPointError")
Function u_existEntryPointError()
Local lRet := .F.
lRet := oRest:getLentryPointError()
if (lRet)
conout("Foi configurado um ponto de função para tratamento de erros: " +
oRest:getCentryPointError())
else
conout("Nao foi configurado ponto de função para tratamento de erros.")
endif

TOTVSTEC – REST
04/2020

• getCentryPointError(see page 163)
5.4.75 Rest:getThreadPoolAuthorizationOnAuth
Retorna o nome da função responsável por realizar a autenticação do serviço
5.4.75.1 Sintaxe
getThreadPoolAuthorizationOnAuth()
5.4.75.2 Retorno
cRet string Nome da função que será executada no momento de

autenticar o serviço.
5.4.75.3 Exemplos
@Get('/documentation/getThreadPoolAuthorizationOnAuth')
Function u_authorizationFunction()
Local cFunc := oRest:getThreadPoolAuthorizationOnAuth()
conout("O usuáro deve implementar as regras de autenticação aqui: " + cFunc)
return
05/2020

TOTVSTEC – REST
5.4.76 Rest:getURLRequest
Retorna a URL da requisição corrente, esse nome corresponde a concatenação da location mais o endpoint de cada
serviço.
5.4.76.1 Sintaxe
getURLRequest()
5.4.76.2 Retorno
cURL string URL utilizada na requisição
5.4.76.3 Exemplos
@Get("/documentation/getURLRequest")
Function u_fGetURLRequest()
Local creturn := ""
creturn := oRest:getURLRequest()
creturn := "{'URL':" + creturn + "}"
conout(cReturn) // Vai exibir api/minhaURL
Return
11/2019
5.4.77 Rest:getUserExit
Getter para atributo que informa se houve a necessidade de sair forçadamente da thread.

TOTVSTEC – REST
5.4.77.1 Sintaxe
getUserExit()
5.4.77.2 Retorno
lRet lógico Se for verdadeiro indica que houve uma manipulação, através
do método setUserExit.T..T., forçando que a espera por novas
requisições seja encerrada.
5.4.77.3 Exemplos
@Get("/documentation/getUserExit")
Function u_fgetUserExit()
Local lRet := .F.
lRet := oRest:setUserExit(.T.)
lRet := oRest:getUserExit()
return oRest:setResponse('{"UserExit": "A próxima requisão não será respondida.
' + cValToChar(lRet) + '"}')
04/2020

• setUserExit(see page 165)
5.4.78 Rest:getXhrRequest
Indica se requisição possui o objeto XHR(XML Http Request).

TOTVSTEC – REST
5.4.78.1 Sintaxe
getXhrRequest()
5.4.78.2 Retorno
lXHR lógico Indica se foi indicado o objeto XHR na

requisição.t..t. e .f..f. caso não.
• Para visualizar o exemplo, execute o Rest no endereço "/documentacao/getxhrrequest""/documentacao/
getxhrrequest"
5.4.78.4 Exemplos
@Get("/documentacao/getxhrrequest")
Function u_fGetXhrRequest()
Local lRet := oRest:getXhrRequest()
cResponse := "O retorno do método getXhrRequest é:"+ cValToChar(lRet)
01/2020
5.4.79 Rest:setUserExit
Setter para atributo utilizado no fluxo de processamento das requisições. Utilize-o se houver a necessidade de
interromper o processamento de novas requisições.

TOTVSTEC – REST
5.4.79.1 Sintaxe
setUserExit( < lSet > )
lSet lógico Se for informado o valor verdadeiro, X

faz com que espera por novas
requisições seja encerrada.
5.4.79.3 Retorno
lRet lógico indica se o método foi executado.
5.4.79.4 Exemplos
@Get("/documentation/setUserExit")
Function u_fsetUserExit()
Local lRet := .F.
lRet := oRest:setUserExit(.T.)
return oRest:setResponse('{"UserExit": "A próxima requisão não será respondida.
' + cValToChar(lRet) + '"}')
04/2020

• getUserExit(see page 167)

TOTVSTEC – REST
5.5 E - Todas as funções
5.5.1 Namespace
tlpp.rest
5.5.2 Funções
• wsRestfulStart(see page 169)
19.0.0.0
5.5.3 wsRestfulStart
Função responsável pelo tratamento do JSON de configuração e pela subida de serviço REST compatibilizando os
antigos WsRestful já existentes no RPO.
5.5.3.1 Namespace
tlpp.rest
5.5.3.2 Sintaxe
wsRestfulStart( < oConfig >, [ cPath ] )
5.5.3.3 Parâmetros
oConfig JsonObject Objeto Json contento todas as X

chaves necessários para
configuração de um servidor REST
cPath string Path virtual que será adicionado

no início do endpoint

TOTVSTEC – REST
5.5.3.4 Retorno
nStart numérico Código de retorno do ID do servidor | Acima de zero significa

sucesso, números negativos indicam erro.
5.5.3.5 Exemplos
function u_doc_wsRestfulStart()
local nResult := 0
local jo := Nil
local cEnv := getenvserver()
local _Port_ := 40011
local _Charset_ := "UTF-8"
local _Server_ := "HTTP_SRV"
local _Location_ := "HTTP_APP"
local _ContentTypes_ := "APP_CONTENTTYPES"
local _ThreadPool_ := "TP_APP"
// HTTP Config
// -----------
jo := JsonObject():new()
jo['HTTPSERVER'] := JsonObject():new()
jo['HTTPSERVER']['Log'] := .F.
jo['HTTPSERVER']['Charset'] := _Charset_
jo['HTTPSERVER']['Servers'] := {_Server_}
jo['HTTPSERVER']['LoadJSON'] := .F.
jo['HTTPSERVER']['OldUrns'] := .F.
// Server Config
// -------------
jo[_Server_] := JsonObject():new()
jo[_Server_]['HostName'] := "TOTVS_HTTP_SERVER"
jo[_Server_]['Port'] := _Port_
jo[_Server_]['ContentTypes'] := _ContentTypes_
jo[_Server_]['Locations'] := { _Location_ }
// Aplicativo
// ----------
jo[_Location_] := JsonObject():new()
jo[_Location_]['Path'] := '/'
jo[_Location_]['RootPath'] := "root/web"
jo[_Location_]['DefaultPage'] := {"index.html"}
jo[_Location_]['ThreadPool'] := _ThreadPool_
// Configuração básica de Thread Pool

TOTVSTEC – REST
jo[_ThreadPool_] := JsonObject():new()
jo[_ThreadPool_]['Environment'] := cEnv
jo[_ThreadPool_]['MinThreads'] := 1
jo[_ThreadPool_]['MaxThreads'] := 4
jo[_ThreadPool_]['MinFreeThreads'] := 1
jo[_ThreadPool_]['GrowthFactor'] := 1
jo[_ThreadPool_]['InactiveTimeout'] := 30000
jo[_ThreadPool_]['AcceptTimeout'] := 10000
// ContentTypes
// ------------
jo[_ContentTypes_] := JsonObject():new()
jo[_ContentTypes_]['htm'] := "text/html"
jo[_ContentTypes_]['html'] := "text/html"
jo[_ContentTypes_]['js'] := "application/x-javascript"
jo[_ContentTypes_]['css'] := "text/css"
jo[_ContentTypes_]['txt'] := "text/plain"
jo[_ContentTypes_]['json'] := "application/json"
jo[_ContentTypes_]['stm'] := "text/html"
jo[_ContentTypes_]['tsp'] := "text/html"
// Inicializa serviço HTTP

// -----------------------
nResult := tlpp.rest.wsRestfulStart( jo, '/myrest' )
return nResult
19.3.0.6

TOTVSTEC – REST
6 5 - APIs
• Configuração em tempo real(see page 172)

• Lista de Serviços disponíveis(see page 173)
• Métricas de tempos(see page 175)
• Monitoramento(see page 179)
• Versão(see page 182)
6.1 Configuração em tempo real

Esta API permite efetuar em tempo real a mudança na configuração dos principais parâmetros referentes
aos LOGS do REST Server TLPP sem que haja a necessidade de um restart dos serviços ou mesmo do server.
Por meio de uma interface simples e intuitiva, é possível alterar os valores dos atributos para a forma mais
conveniente ou necessária afim de que se consiga uma análise mais precisa e detalhada dos logs dos
serviços RESTque são disponibilizados no arquivo console.log do seu Appserver.
A configuração destes valores advém das chaves referentes ao log do RESTque estão na sessão [GENERAL] do
arquivo Appserver.ini, lembrando que não necessariamente as mesmas devem existir, já que a aplicação possui
valores "default".
P.S.: Estes valores são apresentados na tela da API para facilitar a identificação.
6.1.1 Como utilizar

Para utilização desta aplicação basta digitar este endereço no seu navegador: https://localhost:5012/rest/tlpp/rest/
config
• https - Protocolo definido na configuração do HttpServer para as aplicações REST.
• localhost - Endereço(IP/Nome) do seu servidor de aplicação responsável pelo REST.
• 5012 - Porta configurada no Appserver para o REST.
• /rest - Location definida no Appserver para o REST.
• /tlpp/rest/config - URI da aplicação.
Obs.: Todos os parâmetros da URL citados acima, exceto o URI da aplicação, devem ser configurados conforme as
configurações do seu servidor HTTPServer.
Uma tela como a abaixo deverá ser mostrada no seu navegador:
Funcionamento
5 - APIs – 172
TOTVSTEC – REST
Pode ser observado que na tela existem 3 colunas de agrupamento:

• USER VALUE - Valor dos campos que foram digitados pelo usuário.
• INI VALUE - Valor dos campos que foram obtidos na leitura das chaves do arquivo Appserver.ini.
• DEFAULT VALUE - Valor default dos campos.(Utilizado caso não haja configuração das chaves no
arquivo Appserver.ini).
A seguir falaremos sobre os campos para termos uma referência sobre cada um deles:
• OnTime Reload Config - Tempo em segundos para releitura das configuracões do REST em cada Thread.
(Minimo 10s/ Máximo 86400s).
• Print Error - Habilita/Desabilita a impressão do Stack do erro(0 - Desabilitado a impressão do Stack
completo/ 1 - Habilitado em modo full).
• Trace Time - Habilita/Desabilita o contador de tempo de execução de cada rotina(Min: 0 Max: 2).
• Log Level - Nível de detalhamento dos logs (Min: 3 Max: 7).
• Log String Size - Tamanho em KB para cada string de log gerada(Min:10 Max:200).
Ao acionar o botão change setings os valores que estão atribuídos aos campos da coluna USER VALUE, caso
estejam preenchidos, são validados e atualizados on-time no momento do click do botão e seus valores atribuídos
as configurações já passando a valer.
Para facilitar no rodapé da tela, existe a notação: The orange border indicates the value used by the application,
que indica os valores que estão sendo utilizados pela aplicação naquele momento.
6.2 Lista de Serviços disponíveis

Esta API permite obter via método GET uma listagem com todos os endpoints disponíveis no ambiente.
A mesma se utiliza do recurso de annotation disponível na linguagem TLPP, isto além de possibilitar o
desenvolvimento, tornou a sua construção e utilização bem simples, como todo REST nativo na linguagem.
6.2.1 Como utilizar

Pode-se verificar a existência desta API utilizando-se o próprio navegador de internet como: "CHROME" ou então um
client HTTP como por exemplo: "POSTMAN" , para isto basta utilizar um endereço como este exemplo: https://
localhost:5012/rest/tlpp/rest/list/service
• /tlpp/rest/list/service - URI da aplicação.
Obs.: Todos os parâmetros da URL citados acima, exceto: URI da aplicação, devem ser definidos conforme as
O retorno é um JSON, como este do exemplo a seguir:
5 - APIs – 173
TOTVSTEC – REST
A verificação acima não é um item obrigatório, pode ser desconsiderada, mas pode servir de um meio de
averiguação antes do desenvolvimento.

Para utilização desta API pode ser escrito um programa fonte .TLPP implementando uma User Function ou
uma Classe no modelo REST para que seja possível consumir o serviço.
A seguir veremos exemplos com as duas formas de implementação utilizando a mesma URL vista acima.
6.2.1.1 Via User Function
@Get("/tlpp/rest/pegalistaapis")
User Function pegaListaApis()
Local cMethod := "GET"

Local cServer := "https://localhost:5012/rest"
Local cUri := "/tlpp/rest/list/service"
Local cHeadRet := ""
Local cPostParms := ""
Local cGetParms := ""
Local nTimeout := 5
Local aHeadStr := {}
Local jReturn
jReturn := HttpQuote(cServer+cUri, cMethod, cGetParms, cPostParms, nTimeOut,

aHeadStr, @cHeadRet)
Conout(cValToChar(jReturn),"Tipo do retorno["+ValType(jReturn)+"] -->>")
Return
6.2.1.2 Via Classe
class pegaListaApis from LongclassName

public method new() constructor
@Get("/tlpp/rest/pegalistaapis")
public method mPegaListaApis()
endclass
method new() class pegaListaApis

return Self
5 - APIs – 174
TOTVSTEC – REST
method mPegaListaApis() Class pegaListaApis

Local cUri := "/tlpp/rest/list/service"
Local nTimeout := 5
Local jReturn

return .T.
6.2.2 Funcionamento
Nos exemplos descritos no item anterior, pode ser observado a utilização da função HTTPQuote disponível no
binário do Appserver, a mesma simula o funcionamento de um Client HTTP onde são passados os parâmetros com
os dados para que seja efetuada a consulta a API por meio do método GET, que também é enviado como
parâmetro.
Pode ser observado também que o retorno é sempre um JSON, que no caso dos exemplos, é convertido em
uma String para que seja possível a sua visualização no Console.log do server, porém o retorno deve ser trabalhado
conforme a necessidade de implementação.
6.3 Métricas de tempos

Esta API permite obter via método GET uma listagem com o tempo em microssegundos e o percentual gasto na
execução de cada entryPoint na resposta de uma requisição REST.
Com o resultado é possível verificar os valores detalhadamente, pois o consumo está separado por
cada entryPoint, Slave e ThreadPool, tornando esta API indispensável para análise de consumo, não só em caso de
lentidão, mas também quando há necessidade de implementação de um novo entryPoint bem como na
manutenção do ambiente.
6.3.1 Como utilizar

Esta API pode ser utilizada diretamente no próprio navegador de internet como: "CHROME", em um client HTTP
como o: "POSTMAN", ou então, construindo um programa fonte .TLPP.
O retorno é uma string que, caso seja salva como arquivo utilizando a extensão .html, pode ser visualizada como
página web.
A Api ainda disponibiliza os resultados diretamente no arquivo Console.log do ambiente onde está sendo executado
o Appserver.
Sua utilização deve ser feita requisitando um endereço como este, por exemplo: https://localhost:5012/rest/tlpp/
rest/usage/time
5 - APIs – 175
TOTVSTEC – REST


• /tlpp/rest/usage/time - URI da aplicação.
Obs.: Todos os parâmetros da URL citados acima, exceto: URI da aplicação, devem ser definidos conforme as
Caso executado diretamente no navegador, será mostrado uma página como esta:
5 - APIs – 176
uma Classe.
Também é possivel consumir a API por meio de um programa fonte .TLPP escrevendo uma User Function ou
5 - APIs – 177
TOTVSTEC – REST
TOTVSTEC – REST
6.3.1.1 Utilizando User Function.
@Get("/tlpp/rest/metricasdetempo")
User Function metricasDeTempo()

Local cUri := "/tlpp/rest/usage/time"
Local nTimeout := 5
Local jReturn

Return
6.3.1.2 Utilizando Classe
class metricasDeTempo from LongclassName

@Get("/tlpp/rest/metricasdetempo")
public method mmetricasdetempo()
endclass
method new() class metricasDeTempo

return Self
method mmetricasdetempo() Class metricasDeTempo

Local cUri := "/tlpp/rest/usage/time"
5 - APIs – 178
TOTVSTEC – REST

Local nTimeout := 5
Local jReturn

return .T.
6.3.2 Funcionamento
A API coleta os dados de consumo simulando a execução de cada entryPoint em cada Slave e
no ThreadPool principal, guarda os dados iniciais e ao final efetua as comparações e os cálculos conforme as
configurações do ambiente em que foi executada.
O seu retorno é uma string que foi dinamicamente montada e caso seja salva como um arquivo com
extensão .html pode ser mostrada como uma pagina web.
P.S.: Caso haja algum problema, o retorno obedece o mesmo formato, porém é passada a informação do que
causou o mal funcionamento.
6.4 Monitoramento
6.4.1 Monitoramento
Esta API permite obter via método GET uma listagem com o consumo de memória do Appserver detalhado por itens
tais como: Memória Residente, Memória Ram , Memória Ram Livre, etc.
Com o resultado é possível analisar a "saúde" do server, muito útil para monitorar o ambiente permitindo se
antecipara até a um travamento por conta do consumo elevado de memória.
6.4.1.1 Como utilizar

Inicialmente é necessário inserir no arquivo appserver.ini uma seção para que seja habilitado o serviço de
monitoramento servidor de aplicação(Appserver):
[APP_MONITOR]
enable=1
A partir da habilitação do serviço, esta API pode ser utilizada diretamente no próprio navegador de internet
como: "CHROME", em um client HTTP como o: "POSTMAN", ou então, construindo um programa fonte .TLPP.
O retorno da mesma é um arquivo JSON que pode ser utilizado posteriormente da forma que for necessária para a
sua aplicação.
A API possibilita duas formas de consumo:
• /appserver/metrics - O resultado é um arquivo contendo os modos de pesquisa e os campos
disponibilizados pela API.
5 - APIs – 179
TOTVSTEC – REST
• /appserver/metrics?all - O resultado é um arquivo contendo os valores de memória do servidor, sejam

todos ou conforme os dados solicitados na requisição.

No caso o all após a ? representa um filtro utilzando-se da metodologia QueryString
Partindo destes princípios, sua utilização pode ser feita requisitando um endereço como este: https://
localhost:32033/api/*
• https - Protocolo definido como padrão no Appserver para consumo da aplicação de monitoria.
• localhost - Endereço(IP/Nome) do seu servidor de aplicação onde foi habilitado o serviço de monitoria.
• 32033 - Porta definida no Appserver para o serviço de monitoria.
• /api - Location definida no Appserver para o serviço de monitoria.
• ** * ** - URI da aplicação(deve ser substituída por um dos dois endpoints da aplicação).
Caso executado diretamente no navegador, será mostrado uma página como esta para cada endpoint:
/appserver/metrics
/appserver/metrics?all
Também é possível consumir a API por meio de um programa fonte .TLPP escrevendo uma User Function ou

uma Classe.
Utilizando User Function.
@Get("/tlpp/rest/servermonitor")
User Function serverMonitor()

Local cServer := "https://localhost:32033/api"
Local cUri := "/appserver/metrics"
Local cUriAll := "/appserver/metrics/?all"
Local cUriSpc := "/appserver/metrics/?memory_resident"
Local nTimeout := 5
5 - APIs – 180
TOTVSTEC – REST
Local jReturn
//consultando as opções da api com a primeira URI

Conout("Retorno da primeira URI-->> " + cValToChar(jReturn))
//consultando o retorno geral da API

jReturn := HttpQuote(cServer+cUriAll, cMethod, cGetParms, cPostParms, nTimeOut,
Conout("Retorno da consulta geral-->> " + cValToChar(jReturn))
//consultando o retorno de um valor especifico da API

jReturn := HttpQuote(cServer+cUriSpc, cMethod, cGetParms, cPostParms, nTimeOut,
Conout("Retorno da consulta específica-->> " + cValToChar(jReturn))
Return
Utilizando Classe
class serverMonitor from LongclassName

@Get("/tlpp/rest/servermonitor")
public method mServerMonitor()
endclass
method new() class serverMonitor

return Self
method mServerMonitor() class serverMonitor

Local cServer := "https://localhost:32033/api"
Local cUri := "/appserver/metrics"
Local cUriAll := "/appserver/metrics/?all"
Local cUriSpc := "/appserver/metrics/?memory_resident"
Local nTimeout := 5
Local jReturn
5 - APIs – 181
TOTVSTEC – REST
//consultando as opções da api

Conout("Retorno da primeira URI-->> " + cValToChar(jReturn))
//consultando o retorno geral da API

jReturn := HttpQuote(cServer+cUriAll, cMethod, cGetParms, cPostParms, nTimeOut,
Conout("Retorno da consulta geral-->> " + cValToChar(jReturn))
//consultando o retorno de um valor especifico da API

jReturn := HttpQuote(cServer+cUriSpc, cMethod, cGetParms, cPostParms, nTimeOut,
Conout("Retorno da consulta específica-->> " + cValToChar(jReturn))
return .T.
6.4.1.2 Funcionamento
A API coleta os dados diretamente no binário do servidor de aplicação(AppServer), pois como se trata de medições
de consumo de memória não poderia ser diferente.
Seu uso, como demonstrado acima, pode ser feito acessando-a utilizando o endpoint de 3 diferentes formas o que
interfere diretamente no resultado esperado.
• Utilizando o endpoint - appserver/metrics
• O retorno é um arquivo JSON contendo as formas de consulta e os campos disponíveis para filtro.
• Utilizando o endpoint - appserver/metrics?all
• O retorno é um arquivo JSON contendo o resultado do consumo de todas as memórias utilizadas
pelo Appserver.
• Utilizando o endpoint - appserver/metrics?memory_resident
• O retorno é um arquivo JSON contendo o resultado do filtro passado utilizando a
didática QueryString
P.S.: É possível passar mais de um parâmetro para a API concatenando-os seguindo a metodologia QueryString.
6.5 Versão
Esta API permite obter via método GET os valores de versão, build e patch dos principais componentes do
ambiente:
• Appserver
• TLPP
6.5.1 Como utilizar

Esta API pode ser utilizada diretamente no próprio navegador de internet como: "CHROME", em um client HTTP
como: "POSTMAN", ou então, construindo um programa fonte .TLPP.
5 - APIs – 182
TOTVSTEC – REST
O retorno da mesma é um arquivo JSON que pode ser utilizado posteriormente da forma que for necessária para a
sua aplicação.
A API disponibiliza 3 endpoints para consumo:
• /totvs/environment - O resultado é um arquivo contendo o resultado concatenado de versão, build e patch
referente ao Appserver e a linguagem TLPP.
• /appserver/environment - O resultado é um arquivo contendo o resultado de versão, build e patch
referente ao Appserver.
• /tlpp/environment - O resultado é um arquivo contendo o resultado de versão, build e patch referente a
linguagem TLPP.
Partindo destes princípios, sua utilização pode ser feita requisitando um endereço como este: https://
localhost:5012/rest/
• ** * ** - URI da aplicação(deve ser substituída por um dos três endpoints da aplicação).
Caso executado diretamente no navegador, será mostrado uma página como esta para cada endpoint:
6.5.1.1 /totvs/environment
/appserver/environment
/tlpp/environment
Também é possível consumir a API por meio de um programa fonte .TLPP escrevendo uma User Function ou

uma Classe.
6.5.1.2 Utilizando User Function.
@Get("/tlpp/rest/versionenvironment")
User Function versionEnvironment()

Local cUriTotvs := "/totvs/environment"
5 - APIs – 183
TOTVSTEC – REST
Local cUriAppsrv := "/appserver/environment"

Local cUriTlpp := "/tlpp/environment"
Local nTimeout := 5
Local jReturn
//consumindo a api com a URI Totvs

jReturn := HTTPGet(cServer+cUriTotvs, cGetParms, nTimeout, aHeadStr, @cHeadRet)
Conout("Retorno da URI TOTVS-->> " + cValToChar(jReturn))
//consumindo a api com a URI Appserver

jReturn := HTTPGet(cServer+cUriAppsrv, cGetParms, nTimeout, aHeadStr,
@cHeadRet)
Conout("Retorno da URI appserver-->> " + cValToChar(jReturn))
//consumindo a api com a URI Tlpp

jReturn := HTTPGet(cServer+cUriTlpp, cGetParms, nTimeout, aHeadStr, @cHeadRet)
Conout("Retorno da URI Tlpp-->> " + cValToChar(jReturn))
Return
6.5.1.3 Utilizando Classe
class versionEnvironment from LongclassName

@Get("/tlpp/rest/versionenvironment")
public method mVersionEnvironment()
endclass
method new() class versionEnvironment

return Self
method mVersionEnvironment() Class versionEnvironment

Local cUriTotvs := "/totvs/environment"
Local cUriAppsrv := "/appserver/environment"
Local cUriTlpp := "/tlpp/environment"
Local nTimeout := 5
5 - APIs – 184
TOTVSTEC – REST
Local jReturn
//consumindo a api com a URI Totvs

jReturn := HTTPGet(cServer+cUriTotvs, cGetParms, nTimeout, aHeadStr, @cHeadRet)
Conout("Retorno da URI TOTVS-->> " + cValToChar(jReturn))
//consumindo a api com a URI Appserver

jReturn := HTTPGet(cServer+cUriAppsrv, cGetParms, nTimeout, aHeadStr,
@cHeadRet)
Conout("Retorno da URI appserver-->> " + cValToChar(jReturn))
//consumindo a api com a URI Tlpp

jReturn := HTTPGet(cServer+cUriTlpp, cGetParms, nTimeout, aHeadStr, @cHeadRet)
Conout("Retorno da URI Tlpp-->> " + cValToChar(jReturn))
return .T.
6.5.2 Funcionamento
A API consegue obter esses dados internamente efetuando consultas no binário, desta forma foi possível conseguir
os valores disponibilizados tanto do servidor de aplicação, quanto do repositório para o caso do TLPP.
Seu uso, como demonstrado acima, pode ser feito acessando-a utilizando o endpoint de 3 diferentes formas para
que se consiga o resultado esperado da forma mais simples possível.
5 - APIs – 185
TOTVSTEC – REST
7 6 - Exemplos práticos
Nós mantemos um projeto público no GitHub da TOTVS com exemplos práticos para facilitar o aprendizado sobre
essa funcionalidade.
Sintam-se convidados a acessar aqui16 os exemplos de REST.
Aproveitem!
Exemplos:
• CRUD(see page 186)

• Migração WsRESTful para REST tlppCore(see page 186)
7.1 CRUD
GITHUB → https://github.com/totvs/tlpp-sample-rest/tree/master/server/CRUD
Nesse exemplo, temos um CRUD simples simulando um cadastro de usuário.
É possível aprender os seguintes recursos:

• Verbos/Métodos
• GET
• POST
• PUT
• PATCH
• DELETE
• Recebimento de parâmetros
• Query String
• Path Param
• Body Raw
• Resposta
• Mensagem OK
• Mensagem de Erro
7.2 Migração WsRESTful para REST tlppCore

GitHUB → https://github.com/totvs/tlpp-sample-rest/tree/master/server/migrate-FWrest-2-tlpp
7.2.1 Como migrar um REST em FWREST para uso com Annotation (tlppCore)
Nesse projeto [ migrate-FWrest-2-tlpp ] iremos exemplificar através de códigos fontes em ADVPL e TL++ as duas
formas de criar serviços REST.
A primeiro forma será como se cria um serviço REST utilizando o framework Protheus em ADVPL e a segunda como
se cria o mesmo serviço REST, porém agora utilizando o recurso de Annotation em TL++.
16 https://github.com/totvs/tlpp-sample-rest
6 - Exemplos práticos – 186

TOTVSTEC – REST
Sendo assim, teremos 3 (três) códigos fontes, sendo:

Pasta Nome arquivo Linguagem Tecnologia Estrutura
src\ rest-mod01.prw ADVPL framework Protheus classe para REST
src\ rest-mod02.tlpp TL++ annotation user Function
src\ rest-mod03.tlpp TL++ annotation classe genérica
7.2.1.1 Características
Dependências técnicas
• FWREST
a. Binário Lobo-Guará
b. Protheus
c. Framework Protheus
d. License Protheus
e. Conhecimento de Classe
• Annotation
1. Binário Lobo-Guará 2. Core TL++ 3. Conhecimento de annotation
Verbos HTTP suportados

• FWREST
GET
POST
PUT
DELETE
• Annotation
GET
POST
PUT
PATCH
DELETE
7.2.1.2 Resumo das mudanças
Cabeçalho arquivo fonte

• FWREST
#include 'totvs.ch'
#include "restful.ch"

TOTVSTEC – REST
• Annotation
Definição do Verbo HTTP

• FWREST
Para utilizar o WSMETHOD é necessário criar antes WSRESTFUL, tal como é uma declaração de classes,
porém com sintaxe específica para o REST.
WSMETHOD GET
• Annotation
Nesse caso não há dependência de nenhuma classe e é possível utilizar em funções de usuários, funções e
métodos de classes, ficando à gosto do desenvolvedor.
@Get()
EndPoint
• FWREST
A composição para a definição de endpoints nessa versão é composta em dois elementos no fonte.
O primeiro é propriamente o nome da classe de Restful, sendo:
WSRESTFUL sampleMigrateRestProtheus
A outra parte é complementada através da definição da classe, sendo:
WSMETHOD POST ....... WSSYNTAX "/sampleMigrateRestProtheus/{id}"
Podendo ter alterações pelo comando PATH, ex:
WSMETHOD POST ........ PATH "/v2/sampleMigrateRestProtheus/{id}"
• Annotation
Por esse modo, você pode criar o endpoint sem qualquer relação ao nome da classe ou função que será
executada.
A definição do endpoint é através da propriedade "endpoint" da annotation, porém, como ela é a primeira
propriedade, pode-se simplesmente colocar seu valor sem nomear a propriedade.
O exemplo abaixo é a forma simples de definir um endpoint:
@Get("/sampleMigrateRestTlpp")
Pode-se também, definir os path params como segue abaixo:
@Get("/sampleMigrateRestTlpp/:id")
Também é possível definir uma descrição para o endpoint, ex:
@Get(endpoint="/sampleMigrateRestTlpp",description="descrição do método Get")
Parâmetros [ Path Param ]

Essa é forma de passar valores através de URI como complementos dos paths, ex: http://localhost:8080/nomerest/
cliente/:2345
No exemplo acima, 2345 é o path param para o ID do cliente.
• FWREST
Esse modo é possível resgatar os valores de path param através da propriedade (array) ::aURLParms,
conforme exemplo abaixo:

TOTVSTEC – REST
if len(::aURLParms) > 0
cId := ::aURLParms[1]
endif
porém, não é possível buscar nominalmente o valor, e somente através da ordem que ele é declarado na
URI.
• Annotation
O objeto oRest possui um método específico para retornar somente os parâmetros recebidos via Path
Param, sendo:
O retorno do método é uma estrutura em Json com todos os parâmetros recebidos via path param, sendo
assim, é possível resgatar o valor do parâmetro acessando seu valor diretamente no Json através do seu
nome.
Veja abaixo:
cId := jPath[ 'id' ]
Parâmetros [ Query String ]

Essa é o modo de passar valores através de URL após todos os paths e de forma nomeada, ex: http://
localhost:8080/nomerest/cliente?id=2345
No exemplo acima, o parâmetro leva o nome de "id" e tem o valor de 2345.
• FWREST
Para que possa receber parâmetros via query string, é preciso declará-lo como um parâmetro que o método
irá receber, como descrito abaixo:
WSRESTFUL sampleMigrateRestProtheus ......
WSDATA id AS CHARACTER OPTIONAL
.......
WSMETHOD GET WSRECEIVE id .....

Após isso, pode-se utilizá-lo como abaixo:
// Para que não seja NIL
DEFAULT ::id := ''
// Acessa-se diretamente
conout( ::id )
• Annotation
O objeto oRest possui um método específico para retornar somente os parâmetros recebidos via query
string, sendo:
jPath := oRest:getQueryRequest()
O retorno do método é uma estrutura em Json com todos os parâmetros recebidos via query string, sendo
assim, é possível resgatar o valor do parâmetro acessando seu valor diretamente no Json através do seu
nome.
Veja abaixo:
Parâmetros [ Body HTTP ]

• FWREST

TOTVSTEC – REST
cBody := ::GetContent()
• Annotation
cBody := oRest:GetBodyRequest()
Return OK
• FWREST
::SetResponse( cResponse )
• Annotation
oRest:setResponse( cResponse )
Return Error
• FWREST
SetRestFault( nCodeHttp, cMessage )
• Annotation
oRest:setFault( cResponse )
Nesse caso o código HTTP do retorno será 500, caso tenha a necessidade de trocar o código HTTP, utilize
antes o método conforme abaixo:
oRest:setStatusCode( nCodeHttp )
oRest:setFault( cResponse )
7.2.1.3 Exemplos
É importante ressaltar que para simplificar este manual iremos unificar os verbos HTTP "PUT", "POST" e "PATCH",
pois possuem funcionalidades similares no uso em APIs em REST. Porém nos arquivos acima descritos todos os
exemplos estarão presentes.
Exemplo GET
• FWREST
WSRESTFUL sampleMigrateRestProtheus DESCRIPTION "Exemplo de REST framework
Protheus"
WSDATA id AS CHARACTER OPTIONAL
WSMETHOD GET DESCRIPTION "método Get" WSSYNTAX "/

sampleMigrateRestProtheus"
END WSRESTFUL
WSMETHOD GET WSRECEIVE id WSSERVICE sampleMigrateRestProtheus
local cData := ''
::SetContentType("application/json")
DEFAULT ::id := ''

TOTVSTEC – REST
cData := '{ "METHOD" : "GET" ,"id" : "' + ::id + '" }'
::SetResponse( cData )
Return .T.
• Annotation
@Get("/sampleMigrateRestTlpp")
user function GETsampleMigrateRestTlpp()
local cId := ''

local cData := ''
local jPath
jPath := oRest:getQueryRequest()
if ( jPath <> Nil )
if ( valtype(cId) == 'U' )
cId := ''
endif
endif
cData := '{ "METHOD" : "GET" ,"id" : "' + cId + '" }'
oRest:setResponse( cData )
return
Exemplo POST
• FWREST
Protheus"
WSMETHOD POST DESCRIPTION "método Post" WSSYNTAX "/
sampleMigrateRestProtheus/{id}"
END WSRESTFUL
WSMETHOD POST WSSERVICE sampleMigrateRestProtheus
local cId := ''

local cBody := ''
local jBody
endif
::SetResponse( '{ "METHOD" : "POST" ,"id" : "' + cId + '" ' )
cBody := ::GetContent()
jBody:fromJson( cBody )

TOTVSTEC – REST
if ( jBody <> Nil )

if ( !empty(jBody:GetJsonText("cpo1")) )
::SetResponse( ', "cpo1" : "' + jBody:GetJsonText("cpo1") + '"
' )
endif
::SetResponse( ', "cpo2" : "' + jBody:GetJsonText("cpo2") + '"
' )
endif
endif
::SetResponse( ' }' )

Return .T.
• Annotation
@Post("/sampleMigrateRestTlpp/:id")
user function PostsampleMigrateRestTlpp()
local cId := ''

local cData := ''
local jPath
local jBody
if ( jPath <> Nil )
cId := ''
endif
endif
cData := '{ "METHOD" : "POST" , "id" : "' + cId + '" '
jBody:fromJson( oRest:GetBodyRequest() )
if ( jBody <> Nil )
cData += ', "cpo1" : "' + jBody:GetJsonText("cpo1") + '" '
endif
cData += ', "cpo2" : "' + jBody:GetJsonText("cpo2") + '" '
endif
endif
cData += '}'
return
Exemplo DELETE
• FWREST

TOTVSTEC – REST

Protheus"
WSMETHOD DELETE DESCRIPTION "método Delete" WSSYNTAX "/
sampleMigrateRestProtheus/{id}"
END WSRESTFUL
WSMETHOD DELETE WSSERVICE sampleMigrateRestProtheus
local cId := ''

local cData := ''
endif
cData := '{ "METHOD" : "DELETE" ,"id" : "' + cId + '" }'
::SetResponse( cData )
Return .T.
• Annotation
@Delete("/sampleMigrateRestTlpp/:id")
user function DeletesampleMigrateRestTlpp()
local cId := ''

local cData := ''
local jPath
if ( jPath <> Nil )
cId := ''
endif
endif
cData := '{ "METHOD" : "DELETE" , "id" : "' + cId + '" ' + '}'
return

TOTVSTEC – REST
8 Authentication
8.1 oAuth
O REST server possui recurso de ativar a autenticação para as requisições HTTP.
Schemas de Autenticações disponíveis:
• Basic
• oAuth2(see page 197)
8.1.1 Basic
Para a autenticação Basic, é possível também determinar qual função irá fazer a verificação do usuário e senha
enviados pela requisição.
Sendo assim, ao informar o nome da função para o onAuth, o tlppCore irá executar a função do usuário na primeira
ação assim que chegar a requisição.
8.1.2 Configuração
A ativação da autenticação do serviço REST deverá ser feito para cada servidor configurado, ou seja, é possível ter
autenticações diferentes ou até desativadas por servidor.
Porém, não será possível ter autenticações distintas para as Locations e ThreadPool distintas do mesmo servidor,
nesse caso, todos terão a mesma regra de autenticação.
pode consultar aqui17
[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
...
[HTTP_SRV]
tlppdata='{"Authorization":{"scheme":"basic","OnAuth":"onAuthorization"}}'
...
Como a autenticação é um recurso essencialmente da camada tlppCore, sua configuração é feita através da chave
[tlppdata] da sessão do servidor.
Essa chave pode receber duas formas de valores, 1 - string em formato JSON diretamente, ou, 2 - Nome de arquivo
JSON (com path completo ou não), com o conteúdo da configuração.
A segunda forma é útil quando seja necessário um JSON muito extenso, já que as chaves de INIs no appserver
possuem uma limitação na quantidade de caracteres para ser usado.
Para ativar a autenticação, no JSON é preciso informar o modo e a função que será responsável pelas
autenticações, sendo assim, é preciso um JSON conforme o formato a seguir:
{
"Authorization": {
"scheme": "basic",
"OnAuth": "onAuthorization"
17 //tdn.totvs.com/rest_server.md
Authentication – 194
TOTVSTEC – REST
}
}
Note que as informações passadas ao REST, estão dentro de uma chave em nó no JSON com o nome
[Authorization], o modo é informado pela chave [scheme] e a função pela chave [OnAuth].
Nota: Necessário informar um nome válido de função e que esteja compilada no RPO correspondente no
Environment do serviço REST, caso contrário, o tlppCore irá gerar um erro logo na subida do servidor e irá
interromper o start, não ficando disponível.
Abaixo, seguem detalhes de como utilizar cada modo de autenticação disponível no REST server.
8.1.3 BASIC: Como se utiliza?

Ao receber uma requisição HTTP no servidor REST que esteja ativado o modo BASIC, o tlppCore verifica se no
Header possui a seguinte informação:
Authorization: Basic {credenciais em base 64 no formato usuário:senha}
Nesse momento, ainda não é validado o conteúdo de usuário e senha e nem se ele tem o acesso requisitado, é
validado somente se existe essa informação no Header, podendo ter 2 ações, sendo:
[1]
Caso não possua a informação ou não esteja no formato correto, o server não atende a requisição e retorna de
imediato com a mensagem:
{"code":401,"detailedMessage":"","message":"Unauthorized"}
E no Header do HTML a seguinte informação:
WWW-Authenticate: Basic realm="Access to REST", charset="ISO-8859-1"
Com esse retorno, o requisitante tem a condição de adequar a requisição e enviá-la com a informação necessária.
[2]
Caso possua a informação e ela esteja com o formato esperado, então o server irá "Decodar" a base64 onde tenha o
usuário:senha para poder realizar o parse da informação.
Após isso, com os dados já separados, é executada a função definida na chave [onAuth], seguindo a seguinte
assinatura de funcionalidade .
8.1.3.1 Parâmetros
A função customizada recebe 2 (dois) parâmetros, sendo:
1 - cUser
Usuário a ser validado
TOTVSTEC – REST
2 - cPass
Senha a ser validada.
8.1.3.2 Retorno
O retorno é do tipo lógico [boolean], sendo .T. (true) para autenticação com sucesso ou .F. (false) para falha na
autenticação.
Como o tipo retorno deve ser booleano, o server tem uma proteção para quando a função retorne algo diferente do
exigido e irá converter o retorno para booleano, porém para esses casos sempre irá considerar o valor como FALSE.
Sendo assim, o comportamento do REST fica:
Tipo Retorno Valor Valor Considerado
boolean true true
boolean false false
nil --- false
string --- false
numeric --- false
date --- false
array --- false
object --- false
Importante ressaltar que, existindo essa função e o valor considerado for FALSE, será considerado como falha de
autenticação.
8.1.3.3 Exemplo
function onAuthorization( cUser, cPass )
local lRet := .F.
lRet := cUser == 'test_user' .and. cPass == 'test_pass'
return lRet
Caso o retorno seja .F., ou o server considere o retorno inválido, o server não atende a requisição e retorna de
imediato com a mensagem:
TOTVSTEC – REST
{"code":403,"detailedMessage":"","message":"Forbidden"}
E no Header do HTML a seguinte informação:

403 Forbidden
Caso o retorno seja .T., o server segue com o atendimento normalmente à requisição, pois considera que o
requisitante tem as credenciais necessárias para executar o serviço.
8.2 oAuth2
 Abrangência
Disponível a partir da versão 19.3.1 e superiores.
OAuth 2 é um protocolo de autorização que permite que uma aplicação se autentique em outra. Para que isso
aconteça, uma aplicação pede permissão de acesso para um usuário, sem que para isso ela tenha acesso a alguma
senha dele.
Provavelmente você já clicou em algum botão escrito “Logar com sua conta do Google” ou “Logar com sua conta do
Facebook” quando você está em alguma outra aplicação, para evitar de ter que fazer na mão algum cadastro. Neste
caso, você está dando a autorização de uma aplicação terceira a usar os recursos da sua aplicação, neste caso o
Google ou o Facebook. Essas aplicações têm acesso limitado às informações de usuários através do protocolo
HTTP18. OAuth 2 é utilizado nos mais diversos tipos de autenticação, como em telas de login e na autenticação de
APIs (Application Programming Interface)19.
18 https://www.treinaweb.com.br/blog/o-que-e-http-request-get-post-response-200-404/
19 https://www.treinaweb.com.br/blog/o-que-e-uma-api/
TOTVSTEC – REST
A implementação do oAuth2 no TlppCore, apesar de ainda não estar contemplando todas as possibilidades de
validação e acesso disponibilizadas pelo protocolo, ocorreu respeitando a RFC674920 .
Foi implementado, até então, o modelo de utilização abaixo:
• Grant Type -> Client Credentials(Password Grant)
Neste modelo, a partir dos dados do cliente(nome, senha) , juntamente com os dados da aplicação(secret, clientId)
são gerados os tokens access/refresh seguindo o formato de utilização(BEARER).
Apesar do envio de usuário e senha, nesta implementação estes dados não ficam de posse da aplicação de
validação(Server), são descartados após a geração dos tokens ficando a cargo da aplicação Client a guarda e o
envio das mesmas, seja através dos EntryPoints disponibilizados ou dos parâmetros da requisição.
8.2.1 Refresh Token
 Abrangência
Quando é solicitada uma requisição para alguma API em um endereço com o protocolo oAuth2 habilitado, é feita a
validação do Token de Acesso(see page 199) e caso o acesso seja negado por conta do access_token estar expirado,
como no exemplo abaixo :
Deve ser feita uma nova requisição a mesma API TlppCore(“/tlpp/oauth2/token”) utilizando o Refresh Token :
https://localhost:1234/tlpp/oauth2/token?refresh_token=7-oP9sZyBG4Vd-Dd_fS5Yz2l.-
Oky8dNxMSgHXv205_nJNCCSwYhdPk8_kI2zDxz9-
20 https://tools.ietf.org/html/rfc6749
TOTVSTEC – REST
Ui9Rjj4C0plPV0qPuA6SIlT6Ho2CBDy0TtiwnwzYUvF7XxNHfW3li8GNHCoGND6L03Bq_U0QIaUmurVng.Reqoqn-
MXkDnsq3zyboJq4AYB3pSgfS5D5v5wQVJAqU&grant_type=refresh_token21
Onde desmembrando o exemplo temos:

• https:// : Protocolo preferencial para utilização deste endpoint, necessário para utilização de SSL.
• localhost:1234 : Endereço e porta do seu servidor onde o oAuth2 está configurado.
• /tlpp/oauth2/token? : endpoint padrão TlppCore para obtenção de tokens.
• refresh_token - refresh token(o mesmo enviado na solicitação do access token).
• grant_type - refresh_token(enviar como está destacado").
 Os parâmetros da requisição devem ser enviados seguindo a convenção "QueryParams"
Caso seja válido o Refresh Token enviado na requisição, o retorno será um novo Token de Acesso(see page 199) como
resposta desta solicitação :
Resposta de solicitação do Refresh Token
{

"access_token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3THBQQzByMyIsInN1YiI6ImVnaWRpbyIsImlhdCI6MTYwODU1OTY5OSwid
XNlcmlkIjoiN0xwUEMwcjMiLCJleHAiOjE2MDg1NjMyOTl9.Lk3_pCqMboiYWqU12_IyVH9qEVXw6VYT2o3RinpGbJo",

"refresh_token": "7-oP9sZyBG4Vd-Dd_fS5Yz2l.-Oky8dNxMSgHXv205_nJNCCSwYhdPk8_kI2zDxz9-
MXkDnsq3zyboJq4AYB3pSgfS5D5v5wQVJAqU",

"scope": "default",

"token_type": "Bearer",

"expires_in": 3600

}
8.2.2 Token de Acesso
 Abrangência
21 https://localhost:1234/rest/tlpp/oauth2/token?grant_type=password&username=nome
TOTVSTEC – REST
No oAuth2(see page 197) o acesso do cliente a uma API é feito mediante a uma autorização, um token enviado no
header da requisição.
Esse código de acesso ou Access Token é gerado previamente por um servidor de autorização(Authorization Server)
determinado pelo dono da aplicação(Resource Owner).
Para obter o token o cliente deve fazer uma chamada Http POST a API TlppCore através do endereço “/tlpp/
oauth2/token” desta forma :
https://localhost:1234/tlpp/oauth2/token?
grant_type=password&username=nome22dousuario&password=senhadousuario
Onde desmembrando a URL temos:
• https:// : Protocolo preferencial para utilização deste endpoint com utilização de SSL.
• localhost:1234 : Endereço e porta do seu servidor onde o oAuth2(see page 197) está configurado.
• /tlpp/oauth2/token? : endpoint padrão TlppCore para obtenção de tokens.
• grant_type : "password"(enviar a palavra password)
• username - nome do usuário(nome do usuário que está solicitando acesso a aplicação).
• password - senha do usuário(senha do usuário que está solicitando acesso a aplicação).
 Os parâmetros da requisição devem ser enviados conforme a convenção "Query Params".

Assim que é chegada a requisição, é executadas a validações de configuração do ambiente23 e dos
parâmetros enviados na requisição bem como os fornecidos pelo EntryPoint24 antes que os tokens sejam gerados.
Havendo sucesso em todas as validações a requisição é processada e caso não ocorra nenhum erro, é retornada
uma resposta de sucesso(status 200-OK) para o cliente contendo no body da mesma um Json25com o access
token, refresh token, scope, type e expires in(tempo de validade em segundos) :
Resposta de solicitação do Access Token
{

"access_token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3THBQQzByMyIsInN1YiI6ImVnaWRpbyIsImlhdCI6MTYwODU1OTY5OSwid
XNlcmlkIjoiN0xwUEMwcjMiLCJleHAiOjE2MDg1NjMyOTl9.Lk3_pCqMboiYWqU12_IyVH9qEVXw6VYT2o3RinpGbJo",

"refresh_token": "7-oP9sZyBG4Vd-Dd_fS5Yz2l.-Oky8dNxMSgHXv205_nJNCCSwYhdPk8_kI2zDxz9-
MXkDnsq3zyboJq4AYB3pSgfS5D5v5wQVJAqU",

"scope": "default",

"token_type": "Bearer",

22 https://localhost:1234/rest/tlpp/oauth2/token?grant_type=password&username=nome
23 http://tdn.totvs.com
24 http://tdn.totvs.com
25 https://tdn.totvs.com/display/tec/Json
TOTVSTEC – REST
"expires_in": 3600

}
Caso haja falha em alguma das validações prévias a geração do token, é enviado ao cliente uma resposta contendo
o código de erro constando no corpo da mensagem a descrição da falha:
8.2.3 Utilizando o Protocolo oAuth2
 Abrangência
 Correção Inportante
Correção de congelamento de novas solicitações após erro na validação do Token de Acesso(see page 199)
disponíveis no TLPP.RPO com data superior a 01/06/2022
Após configurar o ambiente(see page 202) e entender como funciona o Token de Acesso(see page 199) e o Refresh
Token(see page 198) está na hora de utilizar o protocolo oAuth2 (see page 197)para validação de acesso as APIs.
Para isso siga os passos descritos a seguir:
1. Solicitar um Token de Acesso(see page 199) fazendo uma requisição do tipo "POST" para o EndPoint: "/tlpp/
oauth2/token" enviando os parâmetros: grant_type/username/password.
https://localhost:47500/rest/tlpp/oauth2/token?
grant_type=password&username=josemaria&password=123456abc26
2. Caso todas as configurações tenham sido efetuadas com sucesso, o retorno da requisição acima trará o
Token de Acesso(access_token)(see page 199) que deve ser utilizado para acesso a API desejada.
Para isso no momento da solicitação, o token deve ser enviado no header da requisição desta forma:
Accept: application/json
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJUT1RWUy1BRFZQTC1GV0pXVCIsIn
N1YiI6Im1hcmlvIiwiaWF0IjoxNTUzMDIyMjYwLCJleHAiOjE1NTMwMjU4NjAsInJlc3RyaWN0Z
WR0byI6WyJhcGkvcHJvdGhldXMvIiwiYXBpL2ZyYW1ld29yay8iXX0.jgvejFxPYDchLtj04r7m
i
26 https://localhost:47500/rest/tlpp/oauth2/token?grant_type=password&username=egidio&password=e1g2d3i4o5
TOTVSTEC – REST
Chave Valor Descrição
Accept application/json Formato do conteúdo aceito na

resposta da requisição
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI Token de acesso para permissão de

6IkpXVCJ9.... uso a API requisitada
No momento da recepção da requisição o servidor fará a verificação das configurações executadas e a

validação (see page 203)do token enviado.
Estando tudo correto, a API solicitada será acessada, caso contrário será devolvida na resposta da
solicitação o erro ocorrido na validação.
3. Se no item anterior o retorno da requisição for "token expired", é hora da utilização do Refresh Token(see page
198).
Para isto deve ser efetuada uma requisição do tipo "POST" para o EndPoint: "/tlpp/oauth2/token" enviando
os parâmetros: refresh_token/grant_type.
https://localhost:47500/rest/tlpp/oauth2/token?refresh_token=7-oP9sZyBG4VZ-yR_9K5Yz2l.-
Oky8dNxMSgHXv205_nJNCCSwYhdPk8_kI2zDxz9-Uy-
RAbeC0hbE10qPuA6SIlT6Ho2CBDy0TtiwnwzYUOJ70JrHfeJuC8GNHCoGND6L03Bq_U0QIaUmurVng.B_CLxM
apc9laad5uyx5aMZ7xDDXnS0NqrNqoraDnrEE&grant_type=refresh_token
4. Estando o refresh token (see page 198)íntegro e não expirado, o retorno da solicitação trará uma resposta
idêntica a do item 1, com um novo access_token(see page 199).
Se o refresh token(see page 198) enviado estiver vencido(expirado)(see page 205) deve-se refazer os
procedimentos seguindo os passos desde o primeiro item desta lista para obtenção de um novo Token de
acesso.
8.3 Configuração do Ambiente
 Abrangência
Para utilização do protocolo oAuth2 TlppCore é necessário promover alterações no arquivo de configuração do

AppServer(appserver.ini27).
Foi criada chave a tlppdata, ela deve ser incluída na sessão do HttpServer(see page 59) que irá passar a validar o
acesso às API’s através deste protocolo.
Abaixo veremos um exemplo onde foi configurada uma porta específica para responder às requisições com
validação de acesso pelo oAuth2:
27 https://tdn.totvs.com/download/attachments/342309536/appserver.ini?api=v2&modificationDate=1520349518000&version=1
TOTVSTEC – REST
[HTTPS_OAUTH2_47500_TLPPCORE]
hostname=localhost
port=47500
locations=HTTPS_ROOT_OAUTH2_47500
ContentTypes=CT_HTPP
SslCertificate=_certs\cloud_cert_with_no_chain.pem
SslCertificateKey=_certs\cloud_key.pem
Charset=UTF-8
tlppdata={"Authorization":{"scheme":"oAuth2","onAuth":"", "onAuthNoCheckUri":"resource_oAuth2NoCheckUri",
"onAuthparams":"oAuth2GetParameters"}}
A chave tlppdata é onde devem ser configuradas as funções necessárias para o correto funcionamento do oAuth2
TlppCore.
Ela possui o formato Json28, portanto sua sintaxe deve seguir o modelo de {“key”:”value”} caso contrário, os
valores não serão lidos e será apontado erro de configuração no momento da requisição ou na validação dos
tokens.
Abaixo veremos o detalhamento de cada uma das chaves e seus respectivos valores:
• "Authorization" -> Indica que nesta porta há um protocolo de autorização. A partir do momento que esta
key foi declarada o server exigirá as demais chaves.
• "scheme" -> Deve ser declarado o protocolo de autorização no caso : "oAuth2(see page 197)". Este parâmetro é
obrigatório, não pode ser deixado em branco/null e caso seja colocado um valor diferente de "oAuth2" ou
"oAuth(see page 203)", será apresentado erro na utilização do endpoint.
• "onAuth(see page 203)" -> Inserir o nome da função que irá realizar a checagem do token assim que chegar a
requisição a uma API. Caso seu valor seja declarada : "" (em branco) será utilizada a função padrão TlppCore
para validação do access token .
• "onAuthNoCheckUri(see page 204)" -> Declarar a função responsável por incluir a lista com os endpoints
que não devem ser validados pelo oAuth2. Caso seja declarada : "" (em branco) todos os endpoints exigirão
o access token e serão validados.
• "onAuthparams(see page 205)" -> Declarar a função responsável por enviar os parâmetros privados do cliente
para composição e validação dos tokens(access/refresh). O valor desta chave é obrigatório, não pode ser
deixado em branco/null.
 Observação
É ALTAMENTE recomendado o uso de uma porta HTTPS com protocolo SSL por conta da segurança no
tráfego de informações, evitando inclusive ataques do tipo: man-in-the-midle(MITM)29
8.3.1 onAuth
 Abrangência
Disponível a partir da versão 19.3.1 e superiores
28 https://tdn.totvs.com/display/tec/Json
29 https://www.treinaweb.com.br/blog/termos-comuns-de-seguranca-man-in-the-middle/
TOTVSTEC – REST
No valor desta chave do tlppData, deve ser declarada a função que será a responsável por validar o access token
enviado nas requisições feitas ao servidor. Ela pode ter o seu valor ""(em branco) deixando a validação para a
função padrão do TlppCore, mas se caso for incluso um valor, esta função deve estar devidamente compilada no
environment pois passará a responder pelas validações de acesso as API's.
Essa função recebe 2 parâmetros iniciais:
Parâmetro Tipo Descrição
cToken String Access Token enviado no header da requisição de acesso

a API.
cPath String Uri da requisição para que, se necessário seja tratada

alguma restrição interna.
Após a lógica de validação do token recebido, a função deve devolver um parâmetro de retorno:
Parâmetro Tipo Descrição
lRet Boolean .T. caso o token esteja válido / .F. se o token não
estiver valido
Exemplo de aplicação:
Função de validação
User Function u_validaToken(cToken, cPath)

Local lRet := .F. as Logical
... sua lógica aqui !

Return lRet
8.3.2 onAuthNoCheckUri
 Abrangência
Disponível a partir da versão 19.3.1 e superiores
O valor desta key no tlppdata, quando declarado, informa que existe uma função que informará ao sistema que
existem URI's que não devem ser validadas quando o protocolo oAuth2 estiver ativado.
TOTVSTEC – REST
Se o valor desta chave não for declarada, todas as requisições passarão pela função de validação de access tokens
informada na key onAuth(see page 203).

Esta função não recebe nenhum parâmetro inicial, mas o seu retorno obrigatoriamente deve ser do tipo Array:
Parâmetro Tipo Descrição Obrigatório
aRet Array Array contendo as URI's que não devem ser X

validadas pelo protocolo oAuth2
Exemplo de aplicação:
Função contendo White-List de URI's
User function u_NoCheckUri()

local aRet := {} as Array

aAdd(aRet,'/test/oauth2/nocheckeduri')

return aRet
8.3.3 onAuthparams
 Abrangência
8.3.3.1 Definição
Essa função tem a responsabilidade de carregar as propriedades que serão utilizadas posteriormente tanto na
geração dos tokens(access/refresh), quanto na validação do acesso, sendo a sua declaração e existência da
função responsável obrigatória.
8.3.3.2 Informações importantes

• As propriedades declaradas abaixo sempre devem ter os seus valores incrementados a partir da execução
deste ponto de entrada.
Propriedade Tipo Descrição Exemplo de utilização
client_id Char Identificação do cliente dentro "_1xpto124324523@3"

da corporação
client_secret Char Chave secreta para composição "asdja$d#als!54w5tf@akl"

do token
TOTVSTEC – REST
Propriedade Tipo Descrição Exemplo de utilização
username Char Nome do usuário "nomedousuario"
password Char Senha do usuário "teste123987155asd"
grant_type Char Devido ao modelo "password"

implementado o valor
deve "password"
access_expires Int Tempo de validade do token de 36000

acesso em milissegundos
refresh_expires Char Data de validade do refresh "2022/01/01" ou Date()

token
• No endpoint responsável pela solicitação dos tokens, os parâmetros username e password devem sempre
ser informados no momento da requisição, pois são necessários para a composição do acess token e refresh
token.
• Neste EntryPoint devem ser implementadas todas as lógicas de validação dos parâmetros enviados na
requisição, no caso em específico: username e password. em como como quando não houver.
• O TlppCore disponibiliza um parâmetro inicial que é passado por referência, 30 nele se encontram os
valores dos parâmetros que foram passados na URI de solicitação de token para que a função possa fazer o
trabalho necessário de armazenamento e validação das informações:
Parâmetro Tipo Descrição Obrigatório
jParams JsonObject31 Objeto do tipo Json que contem os X

parâmetros enviados na URI de
solicitação do access token
• Pelo fato de o TlppCore ser um framework independente do produto, optamos por não guardar essas
informações em nossa camada, portanto esse EntryPoint é de total responsabilidade do utilizador, bem
como a sua lógica.
• É imprescindível que as propriedades possuam os mesmos nomes e tipos conforme informado no quadro
do tópico acima: Informações importantes.
• Quando é recebida uma solicitação de acesso, o fluxo de validação passará por este EntryPoint, deve-se
ficar atento para o desenvolvimento desta rotina, uma vez que todas as propriedades devem ser carregadas
para que o token recebido seja válido.
30 http://www.blacktdn.com.br/2009/01/protheus-programao-bsica-em-advpl-combo_8098.html
31 https://tdn.totvs.com/display/tec/Classe+JsonObject
TOTVSTEC – REST
8.3.3.4 Utilização
Exemplo de aplicação com apenas 1 usuário fixo e propriedades carregadas a partir das #define:
Função de Parametrização
#define cliente_secret_ 'secret'

#define cliente_access_expires 3600
#define cliente_refresh_expires Date()+1
#define cliente_id 'clienteId'
#define cliente_oAuth2_user 'nomedoUsuario'
#define cliente_oAuth2_password 'passworddoUsuario'

User function u_paramsProvider(jParams)

local jCliente := {;
"client_id" : client_id , ; // string
"client_secret" : cliente_secret,; // string
"username" : cliente_oAuth2_user ,; // string
"password" : cliente_oAuth2_password ,; // string
"grant_type" : "password",; //string este conteúdo deve ser fixo por enquanto
"access_expires" : 3600,; //integer tempo em milissegundos
"refresh_expires" : Date() + 1,;// ou para o caso de data fixa, o formato deve ser string de data:
"2021/12/31"
"JWTRoutes" : {}; //parametro opcional momentâneamente.
}

//obtendo as propriedades da variável JSon criadas acima para poder popular o objeto nativo jParams que é
passado por referencia.
local aProps := jCliente:GetNames()

//Adicionando as propriedades não existentes no objeto nativo jParams
//Aqui deve-se ficar atento para que todas as propriedades tenham os seus valores carregados, mesmo
quando não estejam presentes no objeto recebido(jParams).
aEval(aProps,{|x,y| iIf(!(jParams:hasProperty(x)), jParams[x] := jCliente[x],'')})
Return

REST v31 20220708 - 230205

Enviado por

Direitos autorais:

Formatos disponíveis

REST v31 20220708 - 230205

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

REST v31 20220708 - 230205

Enviado por

Direitos autorais:

Formatos disponíveis

You are using an UNLICENSED copy of Scroll PDF Exporter for Confluence.

Exported on 07/08/2022

3.1.2.2 Exemplo utilizando função e recebendo parâmetro via query string............................................................... 45

3.3.7.1 Chaves da sessão ................................................................................................................................................. 65

3.3.7.2 Exemplos de configuração .................................................................................................................................. 66

4.3.2 Retorno ................................................................................................................................................................. 85

5 4 - Entendendo o objeto oREST........................................................................87

5.4.4.2 Abrangência ......................................................................................................................................................... 98

5.4.5 oRest:appendKeyHeaderResponse .................................................................................................................... 99

5.4.10.2 Retorno ............................................................................................................................................................... 104

5.4.10.3 Observações ....................................................................................................................................................... 104

5.4.16.1 Sintaxe ................................................................................................................................................................ 109

5.4.16.2 Retorno ............................................................................................................................................................... 109

5.4.21.5 Veja também ...................................................................................................................................................... 115

5.4.22 oRest:getLEntryPointGrader ............................................................................................................................. 115

5.4.28.1 Sintaxe ................................................................................................................................................................ 120

5.4.28.2 Retorno ............................................................................................................................................................... 120

5.4.34 oRest:getThreadPoolAuthorizationScheme..................................................................................................... 125

5.4.34.1 Sintaxe ................................................................................................................................................................ 125

5.4.40 oRest:getThreadPoolMinFreeThreads.............................................................................................................. 131

5.4.40.1 Sintaxe ................................................................................................................................................................ 131

5.4.46 oRest:getThreadPoolServicePort...................................................................................................................... 136

5.4.46.1 Sintaxe ................................................................................................................................................................ 136

5.4.51.5 Abrangência ....................................................................................................................................................... 142

5.4.52 oRest:getThreadPoolUserExitName ................................................................................................................. 142

5.4.58.2 Retorno ............................................................................................................................................................... 146

5.4.58.3 Observações ....................................................................................................................................................... 146

5.4.63.5 Exemplos ............................................................................................................................................................ 152

5.4.63.6 Abrangência ....................................................................................................................................................... 152

5.4.69.5 Abrangência ....................................................................................................................................................... 159

5.4.70 Rest:ExistKeyHeaderResponse.......................................................................................................................... 159

5.4.75.4 Abrangência ....................................................................................................................................................... 164

5.4.76 Rest:getURLRequest .......................................................................................................................................... 165

5.5.3.6 Abrangência ....................................................................................................................................................... 171

8.1.1 Basic.................................................................................................................................................................... 194

8.1.2 Configuração ...................................................................................................................................................... 194

1 REST server (tlppCore)

• 1 - Primeiros Passos(see page 25)

REST server (tlppCore) – 21

• onError(see page 82)

• onSelect(see page 83)

REST server (tlppCore) – 22

• oRest:getThreadPoolMinFreeThreads(see page 131)

• oRest:getThreadPoolMinThreads(see page 132)

REST server (tlppCore) – 23

• oAuth2(see page 197)

• Refresh Token(see page 198)

REST server (tlppCore) – 24

Siga o roterio abaixo para entender e subir rapidamente um serviço REST.

• A - Configuração básica(see page 25)

2.1 A - Configuração básica

2.1.1 Via INI

2.1.1.1 Configuração Rest Server TLPP via INI

Chave Tipo Obrigatório

Define a porta e a natureza dos dados de cada servidor.

2.1.2 Via JSON ( código fonte )

2.1.2.1 Configuração Rest Server TLPP via JSON

Inicialização de um serviço REST dinamicamente

Local sSS_UserExits := ""