TOTVSTEC

Árvore de páginas

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

  • Parâmetros via Query String
    ?param1=value


Agora, olhando parte a parte, conseguimos entender melhor de onde vem cada informação, vamos a elas:


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.


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
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


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.



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.



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.


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.


JSON
user function sLoadURNs()

  local cGetPath := "/api/sample"

  jEndpoints := jsonObject():New()
  jEndpoints[cGetPath] := JsonObject():new()
  jEndpoints[cGetPath]['GET']              := JsonObject():new()
  jEndpoints[cGetPath]['GET']['ClassName'] := ""
  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.



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.

  • Sem rótulos