LightREST: A classe lrServer
A classe lrServer é útil para determinar os parâmetros de execução do servidor LightREST e para iniciar sua execução.
Na versão atual do LightREST, apenas um servidor pode ser instanciado em um executável WinDev® (mas é possível fazer coexistir vários servidores escutando em portas diferentes). Esta limitação será removida em uma versão futura.
A classe lrServer implementa os Membros, Constantes e Métodos descritos abaixo.
Membros
| Membro | Tipo | Descrição |
|---|---|---|
| IPAndPort | String | Interface e porta de escuta (ex: 77.15.224.31:9000). Para escutar todas as interfaces de uma máquina, indicar o endereço IP "0.0.0.0". Escolher um número de porta raramente utilizado. Se a porta escolhida já estiver sendo utilizada por outro processo, a inicialização do servidor LightREST falhará e retornará um erro. Se o endereço IP começar com https://, a conexão será obrigatoriamente criptografada em SSL. |
| TempFolder | String | Diretório temporário utilizado pelo LightREST. Se vazio, o diretório temporário do usuário será utilizado. Atenção: Este membro deve ser definido antes de qualquer chamada a um método de lrServer. Disponível a partir da v2.8 |
| Logger | Booleano | Ativa o registro de log do LightREST (muito detalhado, ative apenas em caso de depuração do componente) |
| Callback | Procedimento | Procedimento chamado automaticamente em caso de parada do servidor (voluntária ou por erro). O procedimento deve receber uma string como parâmetro (que conterá o erro eventual) |
| Monitoring | Booleano | Ativação do monitoramento. O monitoramento adiciona automaticamente a cada resposta REST cabeçalhos contendo os tempos de execução: – Global: "Chrono" – LightREST: "Chrono-LightREST" – Do procedimento REST: "Chrono-Methode" Valor padrão: Falso |
Constantes
| Constante | Descrição |
|---|---|
| MethodGET | Método REST "GET" |
| MethodPOST | Método REST "POST" |
| MethodPUT | Método REST "PUT" |
| MethodDELETE | Método REST "DELETE" |
| MethodHEAD | Método REST "HEAD" |
| MethodPATCH | Método REST "PATCH" |
| MethodOPTIONS | Método REST "OPTIONS" |
Métodos
AddRoute(Rota, Método, Procedimento)
Criação de uma nova Rota associando um par Rota+Método a um procedimento WinDev® (ou procedimento REST)
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Rota | String | A Rota será adicionada automaticamente ao endereço do servidor REST, definido durante a chamada ao método lrServer:Start(). Exemplo: para a rota "minha_bela_rota", a URL de chamada será: http://servidor.com/minha_bela_rota |
| Método | String | Pode conter uma das constantes do tipo lrServer::Method ou um valor literal. |
| Procedimento | Procedimento | Nome do procedimento WinDev que vai receber a requisição REST e retornar o resultado ao cliente (NB: o nome do procedimento deve ser indicado sem parênteses, veja o exemplo). |
Retorno: Nenhum
A rota pode conter elementos variáveis entre chaves {}. Exemplo: /cliente/{id_emp}/{id_cliente}
Neste caso, o LightREST identificará o procedimento vinculado à rota, quaisquer que sejam os parâmetros utilizados. O método lrRequest:GetVarValue() permitirá recuperar os valores passados na rota.
Exemplo 1:
Criação de uma rota /ping com o método GET, que iniciará o procedimento REST pg_Ping
oServer é lrServer
oServer:AddRoute("/ping", lrServer::MethodGET, pg_Ping)
Exemplo 2:
Criação de uma rota /cliente com o método POST, que iniciará o procedimento REST pg_ClienteAdd para criar uma nova entidade
oServer é lrServer
oServer:AddRoute("/cliente", lrServer::MethodPOST, pg_ClienteAdd)
Exemplo 3:
Criação de uma rota /cliente com o método GET, que iniciará o procedimento REST pg_ClienteGet para recuperar dados. Esta rota inclui partes variáveis cujos valores poderão ser recuperados pelo procedimento que gerencia a rota com o método lrRequest:GetVarValue()
oServer é lrServer
oServer:AddRoute("/cliente/{id_emp}/{id_cliente}", lrServer::MethodPOST, pg_ClienteGet)
Kill()
Interrompe a execução do servidor LightREST.
Nenhuma verificação é realizada quanto à execução em andamento de uma função REST. Para garantir que nenhuma interrupção aleatória seja possível, utilize o método Terminate() que aguardará o término de todas as rotas em execução para parar o servidor REST.
Parâmetros: Nenhum
Retorno: Nenhum
Exemplo:
oServer é lrServer oServer:Kill() //O servidor é interrompido...
SetAuthenticationCheckFunction(Procedimento)
Definição da função de verificação automática da autenticação.
Quando um servidor REST contém muitos pontos de entrada, pode ser trabalhoso implementar uma verificação sistemática da identidade, dos direitos do usuário ou da sessão atual.
Quando o método lrServer::SetAuthenticationCheckFunction() é utilizado, o LightREST chamará automaticamente a função passada como parâmetro cada vez que um cliente iniciar uma requisição REST.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Procedimento | String | Nome do procedimento WinDev que gerencia a autenticação |
Retorno: Nenhum
Exemplo:
O código abaixo resultará em uma chamada sistemática a pl_CheckAccess() para cada Rota do servidor executada.
oServer é lrServer oServer:SetAuthenticationCheckFunction(pg_CheckAccess) ... ... oServer:Start() ... ... //Código do procedimento global PROCEDIMENTO pg_CheckAccess(pRequest é stRequest) : booleano bOK é booleano .... Verificação dos direitos de usuário .... Blablablabla .... bOK = (pRequest:GetHeaderValue(pRequest, "check") = "blablabla") RETORNAR bOK FIM
SetGlobalHeaders(Cabeçalhos)
Definição de cabeçalhos OPTIONS (HEADERS) globais.
Quando um servidor REST contém muitos pontos de entrada, pode ser trabalhoso retornar sistematicamente certos cabeçalhos HTTP. O LightREST retornará automaticamente os cabeçalhos definidos aqui, independentemente da rota e do verbo utilizados.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Cabeçalhos | Matriz associativa de Strings | Para cada cabeçalho global (HEADER), contém o valor a ser retornado ao cliente |
Retorno: Nenhum
Exemplo:
Definição dos cabeçalhos automáticos. Eles serão incluídos sistematicamente em cada resposta enviada.
oServer é lrServer taHEAD é matriz associativa de strings taHEAD["Version-Number"] = "123.45" taHEAD["Public-Key"] = "EB6CCD54" oServer:SetGlobalHeaders(taHEAD)
SetGlobalOptionsHeaders(Cabeçalhos)
Definição de cabeçalhos OPTIONS (HEADERS) globais.
Quando um servidor REST contém muitos pontos de entrada, pode ser trabalhoso retornar sistematicamente certos cabeçalhos HTTP.
Isso é válido, por exemplo, quando precisamos usar cabeçalhos do tipo CORS. Esses cabeçalhos autorizam um servidor a distribuir dados para usuários externos. Uma vez definidos os cabeçalhos OPTIONS globais, o LightREST responderá automaticamente com os cabeçalhos CORS aos sistemas remotos que os solicitarem, independentemente da rota em questão (no verbo OPTIONS).
Para mais detalhes sobre CORS, veja AQUI.
Nota: ainda é possível, obviamente, responder às requisições do tipo OPTIONS declarando a rota correspondente com o método lrServer::MethodOPTIONS. Este método será executado em substituição à rota OPTIONS automática do LightREST.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Cabeçalhos | Matriz associativa de Strings | Para cada cabeçalho global (HEADER), contém o valor a ser retornado ao cliente |
Retorno: Nenhum
Exemplo:
Definição dos cabeçalhos automáticos do tipo CORS para permitir requisições cross-domain. Eles serão retornados automaticamente para cada requisição OPTIONS recebida.
oServer é lrServer taCORS é matriz associativa de strings taCORS["Access-Control-Allow-Origin"] = "*" taCORS["Access-Control-Allow-Headers"] = "Content-Type" oServer:SetGlobalOptionsHeaders(taCORS)
SetHTTPSCertificate(Certificado, Chave privada)
Definição dos certificados HTTPS / SSL existentes.
Para usar no modo https:// se você possui um certificado. Isso não é obrigatório. Na ausência de um certificado SSL, o LightREST gerará automaticamente um certificado (não assinado).
Se o membro IpAndPort não tiver o prefixo https://, o certificado SSL não será utilizado.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Certificado | String | Conteúdo do Certificado SSL |
| Chave Privada | String | Conteúdo da chave privada |
Retorno: Nenhum
Exemplo:
Inicialização de um servidor LightREST em modo SSL com o certificado fornecido.
oServer é lrServer
bStartOK é booleano
cErrMess é cadeia
cCertificado é cadeia = fCarregaTexto("./certif_ssl.crt")
cChavePrivada é cadeia = fCarregaTexto("./certif_ssl.key")
oServer:IpAndPort = "https://0.0.0.0:9800"
oServer:SetHTTPSCertificate(cCertificado, cChavePrivada)
(bStartOK, cErrMess) = oServer:Start()
SE NÃO bStartOK ENTÃO
Erro(cErrMess)
RETORNA
FIM
SetLetsEncryptParameters(Domínio(s), Email, Caminho de armazenamento do certificado, prazo de renovação)
Definição dos parâmetros para geração de um certificado Let's Encrypt.
Para usar no modo https://
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Domínio(s) | String ou Matriz de Strings | Domínio(s) para os quais o certificado deve ser gerado |
| String | Email de contato | |
| Caminho certificado | String | Opcional: Caminho de armazenamento do certificado Let's Encrypt (por padrão no diretório do executável) |
| Prazo de renovação | Inteiro | Opcional: Prazo expresso em dias. Assim que a data de expiração do certificado menos este prazo for atingida, o LightREST renovará automaticamente o certificado SSL junto ao Let's Encrypt |
Retorno: Nenhum
Exemplo:
Inicialização de um servidor LightREST em modo HTTPS com geração automática de um certificado SSL Let's Encrypt, armazenado no diret