Routes

Visão Geral

Route é a entidade responsável por definir como as requisições que chegam (do consumidor da API) serão roteadas para os serviços de backend. Ou seja, são regras de roteamento que dizem ao API Gateway (DHuO ou Kong) como encaminhar uma requisição para um serviço.

Um exemplo prático: para expor no DHuO uma API de clientes com a rota /clients hospedada em http://clients-backend:8080 é necessário configurar um Endpoint Service apontando para esse endereço de backend. Na sequência, é necessário configurar uma rota com o path /clients associada ao serviço cadastrado. Assim, ao receber uma requisição com o caminho /clients, o API Gateway redirecionará para o serviço de backend no endereço http://clients-backend:8080/clients.

Mapeamento Especificação de API x API Gateway

Partindo da abordagem Design First adotada no DHuO, existe um vínculo entre os paths cadastrados na especificação da API e a configuração de rotas para exposição no API Gateway. O cadastro de rotas é baseado nos paths declarados na especificação da API. A partir deles, é sugerido uma pré configuração da rota com o path no formato aceito pelos gateways DHuO e Kong. Com isso, a configuração se torna mais ágil.

Além disso, o DHuO sugere opcionalmente a configuração de rota para o método OPTIONS. Normalmente esse método não é documentado nas especificações de APIs, mas pode ser necessário configurá-lo caso a API seja consumida por uma aplicação devido a políticas de CORS (Cross-Origin Resource Sharing). Dessa forma, o DHuO sempre sugerirá sua configuração como acelerador, sendo opcional.

Na lista de rotas existem dois botões para auxiliar na sincronização entre especificação e configurações do API Gateway, útil especialmente para APIs com muitas rotas:

• Rotas pendentes de configuração: acessado pelo botão ⚠️, apresenta a lista de rotas que estão relacionadas na especificação, mas que ainda não foram configuradas como Routes para exposição no API Gateway.
• Desvincular rotas: acessado pelo botão 🔁, apresenta a lista de rotas configuradas como Routes para exposição no API Gateway, mas que não existem mais na especificação. Nesse caso, indicam rotas que não condizem com a documentação da API e deveriam ser removidas das configurações do API Gateway. Essa ação remove todas essas rotas que não estão mais acessíveis pela interface devido a remoção dos paths da especificação.

Compatibilidade com Kong Gateway

O DHuO compreende o ciclo de vida de APIs que utilizam o protocolo HTTP (REST e SOAP). Por sua vez, a configuração da entidade Route no Kong permite configurações de roteamento de outros protocolos além de HTTP/HTTPS. Essas configurações não estão disponíveis nas configurações pela interface do DHuO, mas podem ser feitas utilizando o DHuO CLI. São elas:

• Protocols: opções grpc, grpcs, tcp, tls, udp, tls_passthrough
• Sources: configurações de roteamento baseadas em endereços IPs, disponível para as opções de protocols tcp, tls e udp
• Destinations: configurações de roteamento baseadas em endereços IPs, disponível para as opções de protocols tcp, tls e udp

Por padrão o Kong também permite a configuração de múltiplos paths e métodos em uma única rota. Atualmente, devido à relação com a especificação da API, o DHuO configura rotas na relação 1 para 1: um path e um método por configuração.

Configuração

As rotas são gerenciadas pela interface do estúdio da API. A partir da home, acesse o menu > APIs. Na página de APIs, visualize a API desejada e acesse o menu > Gateway. Crie ou acesse a configuração do tipo de gateway DHuO Gateway ou Kong. Na página de rotas, elas podem ser cadastradas, editadas e excluídas conforme a lista de rotas extraídas da especificação da API.

Permissões

Por fazerem parte das configurações de políticas de gateway, apenas usuários com papel de administrador da organização (Org Admin) ou provedor de APIs (API Provider) podem gerenciar rotas. Para saber mais, acesse a seção Papéis e permissões.

Parâmetros

Aqui estão os parâmetros para a criação de uma rota:

• Nome: Obrigatório. Identificador único da rota que será criada no gateway durante a implantação. O nome não pode conter espaços e pode conter apenas letras sem acentos, números e os caracteres ., -, _ e ~. Para evitar possíveis conflitos durante a implantação com outras APIs, o DHuO sugere automaticamente o padrão com o nome da API, sua versão, método e path.
• Path: Obrigatório. Path da API a ser roteado pelo gateway. Deve começar com / para path fixo ou ~/ para path contendo expressões regulares (regex). Caso o path contenha parâmetros dinâmicos, por exemplo, /pets/{id}, é necessário informar uma expressão regular para que o gateway consiga identificar e rotear as requisições corretamente. Para abstrair complexidades técnicas e evitar conflitos, o DHuO sugere por padrão a conversão do path da especificação para o formato aceito pelos gateways DHuO e Kong.
• Método: Obrigatório. Método HTTP da rota. Deve estar em formato upper case (todas as letras em maiúsculo). Extraído automaticamente da especificação.

Configurações avançadas

• Tags: Lista opcional de tags, para agrupamento de cadastros no gateway.
• Strip path: Obrigatório. Indica se o path deve ser cortado ao realizar o redirecionamento para o endpoint de backend. Por padrão o path original é repassado como parte da url do endpoint de backend (opção desabilitado). Por exemplo, para Service http://backend.local/api, Route Path /legacy e requisição https://dhuo/legacy/pets/123, a url de destino será:
  • Strip path desabilitado (padrão): http://backend.local/api/legacy/pets/123
  • Strip path habilitado: http://backend.local/api/pets/123
• Path handling: Obrigatório. Determina como os paths do Service e Route são concatenados para formar a url de destino para encaminhamento da requisição. Opções: v0, v1. A opção v1 está depreciada a partir de versões 3.x do DHuO e Kong. A opção v0 indica que a composição da url de destino será conforme exemplo anterior considerando a configuração Strip path.
• Regex priority: Obrigatório. Número utilizado para escolher qual rota será utilizada pelo gateway quando várias rotas com regex em paths correspondem ao path recebido. Quando duas rotas correspondem ao path e têm a mesma prioridade, a mais antiga implantada será utilizada. Em caso de prioridades diferentes, a que possuir a maior prioridade será utilizada.
• HTTPS redirect status code: Obrigatório. O status code de resposta que o gateway responde quando ocorre o match da requisição recebida e uma rota existente, porém o protocolo recebido foi HTTP em vez de HTTPS. Observação: essa configuração se aplica apenas se a rota estiver configurada para aceitar apenas o protocolo HTTPS. Opções: 426, 301, 302, 307, 308.
• Protocols: Obrigatório. Lista de protocolos aceitos pela rota. Opções: http, https.
• Hosts: Lista opcional de hosts que correspondem a esta rota. Válido para cenários onde o gateway possui subdomínios e pode ser utilizado como critério adicional de roteamento. Um exemplo prático seria utilizar a mesma instância de gateway para atender mais de um ambiente. O gateway seria disponibilizado nos endereços dev.gateway.dhuo.com e qa.gateway.dhuo.com. A partir disso, poderiam ser configurados dois Services (pets-api-dev para o backend http://backend-dev.internal, pets-api-qa para o backend http://backend-qa.internal) com rotas com o mesmo path /pets, porém com hosts diferentes (dev.gateway.dhuo.com e qa.gateway.dhuo.com). Aceita wildcards, como, por exemplo, *.gateway.dhuo.com
• Headers: Lista opcional de cabeçalhos e valores aceitos como critério adicional de roteamento. Serão considerados o nome do header e um dos valores cadastrados para correspondência da rota. Quando os cabeçalhos contêm apenas um valor e esse valor começa com o prefixo especial ~*, o valor é interpretado como uma expressão regular.
• SNIs: Lista opcional de domínios que, quando o protocolo configurado é https, permite ao gateway rotear requisições com base no nome de domínio que o cliente está tentando acessar durante o handshake TLS/SSL. Um exemplo prático seria permitir que um único gateway (com um único IP e porta 443) sirva múltiplos domínios HTTPS, cada um com seu próprio certificado SSL/TLS. Nesse cenário, os certificados do tipo server também seriam cadastrados e implantados no DHuO, um para cada domínio do respectivo SNI. A diferença para a propriedade hosts está no fato de que hosts realiza a correspondência com o cabeçalho HTTP Host (que vem após o handshake TLS), enquanto snis realiza a correspondência com o nome de domínio durante o handshake do TLS/SSL em si. Aceita wildcards, como, por exemplo, *.gateway.dhuo.com
• Preserve host: Obrigatório. Indica se o gateway deve enviar o cabeçalho Host original recebido do cliente (aquele que o cliente usou para acessar o gateway) para o serviço de backend (configurado no Service). Por padrão, o gateway encaminha para o endereço do serviço backend cadastrado no Service (não preserva o host). Habilite quando o backend precisar saber o domínio original que o cliente utilizou para acessar o gateway. Um exemplo prático para preservar o host seria se o próprio backend servisse múltiplas aplicações e utilizasse o cabeçalho Host da requisição para saber qual aplicação servir, como aplicações multi-tenant. Isso também é comum com servidores web como Nginx ou Apache, por exemplo.
• Request buffering: Obrigatório. Indica se o gateway deve receber todo o payload da requisição do cliente antes de encaminhá-lo ao serviço de backend ou se deve enviá-lo em streaming conforme o recebe. Desabilite essa opção se a rota lidar com uploads de arquivos muito grandes, streaming de dados, ou se a latência e o consumo de memória do gateway forem críticos para essas requisições. Por outro lado, se utilizar algum plugin que dependa da análise do payload recebido para funcionar, é necessário que essa opção esteja habilitada.
• Response buffering: Obrigatório. Complemento da propriedade Request buffering, indica se o gateway deve receber todo o payload da resposta do serviço de backend antes de encaminhá-lo ao cliente ou se deve enviá-lo em streaming conforme o recebe.

Cuidado!

Ao excluir uma rota, todas as configurações de plugins relacionadas a ele serão removidas.

Ao excluir um path da especificação, a configuração de rota não é excluída! É necessário removê-la pela opção Desvincular rotas, explicada anteriormente.