Roteamento dinâmico de solicitações com regras de roteamento do HAQM API Gateway

Por Anton Aleksandrov, arquiteto de soluções principal para Serverless na HAQM Web Services (AWS) e Giedrius Praspaliauskas, Arquiteto de soluções senior de Serverless na HAQM Web Services (AWS).

Recursos eficazes de gerenciamento e roteamento de APIs são cruciais para organizações que gerenciam arquiteturas de aplicativos complexas. Se você é uma empresa de tecnologia lançando novas versões de API para milhões de usuários ou uma organização de serviços financeiros realizando testes A/B para otimizar as experiências do cliente, a capacidade de direcionar o tráfego da API de forma dinâmica e eficiente é essencial.

Hoje, o HAQM API Gateway anuncia o suporte a regras de roteamento dinâmico para nomes de domínio personalizados em todas as regiões compatíveis da AWS. Esse novo recurso permite rotear solicitações de API com base nos valores do cabeçalho HTTP, de forma independente ou em combinação com caminhos de URL. Nesta postagem, você aprenderá a usar esse novo recurso para implementar estratégias de roteamento, como controle de versão de API e lançamentos graduais, sem modificar seus endpoints de API.

Visão geral das regras de roteamento dinâmico

Muitas organizações precisam de recursos dinâmicos de roteamento de API para apoiar suas necessidades comerciais em evolução. Como pessoa de linha de negócios, você quer poder testar novas experiências de usuário com segmentos específicos de clientes, mantendo intactos os fluxos existentes. Como engenheiro, você quer ser capaz de manter várias versões de API em diferentes aplicativos clientes e, ao mesmo tempo, garantir a conformidade regulatória. Antes desse lançamento, os desenvolvedores que usavam o API Gateway implementaram o roteamento dinâmico usando caminhos de URL diferentes, como “/v1/products” e “/v2/products”.

Com esse novo lançamento, você pode implementar a lógica de roteamento dinâmico com uma configuração declarativa simples dentro das configurações personalizadas do nome de domínio. O novo mecanismo de regras de roteamento permite que você tome decisões de roteamento com base em cabeçalhos HTTP, caminhos base ou uma combinação de ambos. Os desenvolvedores não precisam mais criar novos caminhos ou alterar caminhos existentes para fazer uma transição suave entre as versões da API. Eles podem simplesmente especificar o valor desejado no cabeçalho HTTP da solicitação. Entre outras possibilidades, você pode implementar roteamento de arquitetura baseado em células, testes A/B ou seleção dinâmica de backend com base no nome do host, ID do locatário, tipo de mídia de resposta aceita ou valor do cookie. Ao implementar a lógica de roteamento diretamente no API Gateway, você pode eliminar camadas de proxy e estruturas complexas de URL, mantendo um controle refinado sobre o tráfego da API. Esse novo recurso se integra perfeitamente aos recursos existentes do API Gateway e oferece suporte a APIs REST públicas e privadas. O diagrama a seguir mostra como você pode usar regras de roteamento para roteamento baseado em cabeçalho e caminho base. Este exemplo usa um recurso de nível único /products para mostrar a correspondência de caminhos. No entanto, dependendo do seu caso de uso, você também pode usar caminhos de vários níveis, como /products/items.

Figura 1. Usando regras de roteamento para roteamento baseado em cabeçalho e caminho base

Na seção a seguir, você aprenderá como implementar o roteamento baseado em cabeçalhos, usar a nova construção de regras de roteamento para cenários comuns, como controle de versão de API e testes A/B, e configurar regras com diferentes condições e prioridades de roteamento para alcançar o comportamento desejado.

O que é uma regra de roteamento

Uma regra de roteamento é um novo tipo de recurso associado exclusivamente a um único domínio personalizado. Ela representa uma coleção de condições que, quando combinadas, fazem com que a solicitação recebida seja encaminhada para uma API e um estágio específicos. As regras de roteamento têm três propriedades de configuração:

• A propriedade Conditions define os critérios que devem ser atendidos para que as ações sejam tomadas. Uma regra pode incluir até duas condições de cabeçalho e uma condição de caminho base, e todas as condições especificadas devem ser atendidas para acionar a ação. Se nenhuma condição for definida para uma regra, ela servirá como uma regra abrangente que corresponde a todas as solicitações.
• A propriedade Actions define quais ações serão tomadas quando as condições da regra forem atendidas. No momento desse lançamento, a ação suportada está invocando qualquer estágio de qualquer API REST dentro dos mesmos limites de conta e região.
• A propriedade Priority define a ordem em que as regras são avaliadas, com 1 sendo a prioridade mais alta e 1.000.000 a mais baixa. Você não pode reutilizar o mesmo valor de prioridade para mais de uma regra. A AWS recomenda que você deixe um amplo espaço entre as regras sequenciais para facilitar a adição de novas regras no futuro, por exemplo, use 100, 200, 300 em vez de 1, 2, 3.

As condições do cabeçalho, especificadas por meio de uma propriedade matchHeaders, são usadas para corresponder aos valores do cabeçalho da solicitação HTTP, como x -version=v1. Em conformidade com a RFC 7230, os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas, enquanto os valores dos cabeçalhos sim. Você também pode usar curingas nos valores do cabeçalho para prefixo, sufixo e contém correspondência. Veja os exemplos a seguir usando os modelos do AWS CloudFormation:

Correspondência exata:

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "alpha-v2-latest"

Só corresponderá a x-version=alpha-v2-latest

Correspondência de prefixo:

- MatchHeaders: 
	AnyOf: 
	- Header: "x-version" 
	ValueGlob: "*latest"

Corresponde a x-version=alpha-v2-latest, mas não a x-version=alpha-v2

Correspondência de sufixo:

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "alpha*"

Combinará x-version=alpha-v2-latest e x-version=alpha-v1, mas não x-version=beta-v1

Prefixo e sufixo coincidem.

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "*v2*"

Corresponde a x-version=alpha-v2-latest e x-version=beta-v2-test, mas não a x-version=alpha-v1

A condição do caminho base, especificada por meio da propriedade matchBasePaths, é usada para corresponder ao caminho da solicitação de entrada. A correspondência diferencia maiúsculas de minúsculas.

- MatchBasePaths: 
	AnyOf: 
		- "products"

Você pode ter até duas condições MatchHeaders e uma MatchBasePaths por regra de roteamento. As condições são avaliadas usando o operador AND, o que significa que todas as condições devem ser atendidas para que a ação seja tomada. Ambos os tipos de condição oferecem suporte a um único valor de comparação na propriedade AnyOf. O trecho a seguir ilustra um exemplo de regra de roteamento com duas condições MatchHeaders e uma única condição MatchBasePaths.

ProductsV1RoutingRule: 
	Type: 'AWS::ApiGatewayV2::RoutingRule' 
	Properties: 
		DomainNameArn: !Sub "arn:aws:apigateway:${AWS::Region}::/domainnames/${ApiCustomDomain}" 
		Priority: 100 
		Conditions: 
			- MatchHeaders: 
				AnyOf: 
					- Header: "x-version" 
					ValueGlob: "v2" 
			- MatchHeaders: 
				AnyOf: 
					- Header: "x-user-cohort" 
					ValueGlob: "beta-testers" 
			- MatchBasePaths: 
				AnyOf: 
					- "products" 
		Actions: 
				- InvokeApi:
					ApiId: !Ref ProductsV2Api 
					Stage: !Ref ProductsV2Stage

Essa regra corresponde às solicitações para http://example.com/products quando as duas condições do cabeçalho são atendidas — x-version=v2 e x-user-cohort=beta-testers. Essa regra não corresponde a solicitações para nenhum outro caminho base, como http://example.com/orders, ou solicitações que não correspondam a pelo menos uma condição de cabeçalho.

Para cenários como controle de versão de API, você pode criar regras que avaliam cabeçalhos como “aceitar” ou “versão” para direcionar o tráfego para diferentes implementações de API. Por exemplo, para rotear solicitações contendo “x-version: api-beta” para sua API beta, você criaria uma regra especificando essa condição de cabeçalho e configuraria a ação a ser roteada para sua implantação de API beta.

O roteamento baseado em cabeçalhos também simplifica os testes A/B, permitindo que você defina coortes de clientes com base em cabeçalhos personalizados, permitindo experimentos controlados com configurações diferentes. Você pode criar regras que verifiquem um cabeçalho personalizado, como “x-test-group”, para direcionar usuários específicos para diferentes implementações de API. O sistema de prioridade garante um comportamento de roteamento previsível — quando várias regras correspondem a uma solicitação, a regra com o menor número de prioridade (maior precedência) determina o roteamento. A combinação das condições do cabeçalho e do caminho em uma única regra permite cenários de roteamento complexos, como roteamento específico da versão para recursos específicos da API, em vez de toda a API, conforme ilustrado no diagrama a seguir.

Figura 2. Uma configuração de roteamento com duas condições de cabeçalho e um caminho no console do API Gateway.

Consulte a documentação do API Gateway para obter um guia detalhado sobre a criação de regras de roteamento.

Configurando o modo de roteamento

Antes de começar a criar regras de roteamento, você deve primeiro criar pelo menos uma API, um estágio e um nome de domínio personalizado. Você pode configurar seu nome de domínio personalizado com a nova configuração do modo de roteamento.

• Somente mapeamentos de API. Esse é o modo padrão. Ao usar esse modo, você pode continuar usando mapeamentos de caminhos básicos para rotear solicitações para diferentes APIs e não usar regras de roteamento. Esse modo mantém o comportamento atual, em que as solicitações são roteadas com base somente nos mapeamentos do caminho base.
• Regras de roteamento e mapeamentos de API. Com esse modo, você pode usar as regras de roteamento enquanto continua mantendo os mapeamentos do caminho básico como alternativa. Quando você usa esse modo, as regras de roteamento sempre têm precedência e as solicitações sem correspondência são avaliadas em relação aos mapeamentos de caminhos básicos. Esse modo é útil para fazer a transição gradual de suas APIs para regras de roteamento.
• Somente regras de roteamento. Esse modo oferece a flexibilidade de usar somente regras de roteamento e não depender dos caminhos básicos que você pode ter criado anteriormente no domínio usando mapeamentos de API. Esse é o modo de roteamento recomendado; é útil quando você está começando com um novo domínio personalizado ou finalizando a transição dos mapeamentos de API para as regras de roteamento de um domínio personalizado existente.

Ao mudar de um modo de roteamento para outro, sempre teste primeiro sua nova configuração em ambientes que não sejam de produção. Por exemplo, ao alternar o modo de apenas mapeamentos de API para somente regras de roteamento, seu tráfego será roteado somente com regras de roteamento; os mapeamentos de API existentes não entrarão mais em vigor.

Integração ao roteamento baseado em cabeçalhos

Você pode adotar o novo roteamento baseado em cabeçalho para seus domínios personalizados existentes do API Gateway com uma abordagem sem tempo de inatividade e risco minimizado. A primeira etapa é configurar seu domínio personalizado para usar as regras de roteamento e depois o modo de mapeamento de API usando o console do API Gateway, o AWS CLI ou sua ferramenta de infraestrutura como código (IaC). Essa configuração garante que, enquanto você cria gradualmente as regras de roteamento, seus mapeamentos de caminho base existentes continuem funcionando como rotas alternativas. Como as regras de roteamento são avaliadas antes dos mapeamentos do caminho base e, na ausência de regras correspondentes, as solicitações retornam automaticamente aos mapeamentos do caminho base existentes, o tráfego atual da API permanece inalterado durante essa transição.

Depois de configurar o modo de roteamento, você pode introduzir progressivamente as regras de roteamento junto com a configuração existente. Por exemplo, você pode começar criando uma regra com um cabeçalho de teste específico que encaminha para uma nova versão da API, permitindo validar o comportamento de roteamento com tráfego de teste controlado enquanto o tráfego de produção continua fluindo pelos mapeamentos de caminho base existentes. À medida que você ganha confiança na nova configuração de roteamento, você pode expandir gradualmente suas regras, ajustar as prioridades e, opcionalmente, migrar totalmente dos mapeamentos de caminhos básicos. Essa abordagem incremental, combinada com os recursos de observabilidade do API Gateway descritos na próxima seção, permite validar cada alteração e garantir que seus consumidores de API não sofram interrupções durante a transição.

Observabilidade

O API Gateway fornece visibilidade abrangente de como suas regras de roteamento estão processando solicitações por meio do registro de acesso. Cada solicitação agora inclui variáveis de contexto adicionais que ajudam você a entender o processo de decisão de roteamento. A variável $context.customdomain.routingRuleIDMatched identifica qual regra foi correspondida e aplicada à solicitação, enquanto variáveis existentes, como $context.domainName, $context.APIID e $context.stage, fornecem o contexto de roteamento completo. Ao analisar esses registros de acesso, você pode verificar o comportamento do roteamento, solucionar problemas de rotas inesperadas e obter informações sobre padrões de tráfego em diferentes versões de API ou variantes de teste.

Exemplo de ponta a ponta

Considere um cenário real em que uma equipe precisa migrar gradualmente os usuários para uma nova versão da API, como uma plataforma de comércio eletrônico atualizando sua API de checkout da v1 para a v2. Primeiro, a equipe cria duas APIs REST diferentes — uma para cada versão. Em seguida, eles configuram uma regra de roteamento com prioridade 100 que verifica o cabeçalho x-version=v2 e encaminha as solicitações correspondentes para a API v2. Eles também criam outra regra com prioridade 200 que encaminha todas as solicitações com caminhos começando com /checkout para a API v1 como alternativa.

Figura 3. Transição gradual de clientes da API v1 para a v2.

No código do aplicativo, eles adicionam o cabeçalho x-version para uma pequena porcentagem de usuários. Eles monitoram o desempenho e as taxas de erro usando os recursos de telemetria do API Gateway, rastreando os registros de acesso e execução, juntamente com as métricas emitidas. À medida que sua confiança aumenta, eles aumentam gradualmente a porcentagem de usuários que enviam o cabeçalho v2. Essa abordagem garante uma migração controlada com risco mínimo e capacidade de reverter rapidamente, simplesmente removendo o cabeçalho das solicitações ou alterando uma regra de roteamento.

Exemplo

Siga as instruções neste repositório do GitHub para provisionar um exemplo na sua conta da AWS. O projeto ilustra o uso do roteamento dinâmico com o API Gateway.

Conclusão

O roteamento baseado em cabeçalho traz vantagens significativas para os usuários do API Gateway. A compatibilidade com versões anteriores do recurso garante um caminho de transição suave — você pode manter os mapeamentos de caminho base existentes enquanto adota gradualmente as regras de roteamento ou usar os dois mecanismos simultaneamente com a opção de fallback. Essa flexibilidade permite que você migre no seu próprio ritmo sem interromper os aplicativos existentes. A solução é econômica, sem custos adicionais pelo uso de regras de roteamento em APIs REST. Ele reduz os requisitos para aproveitar serviços e infraestrutura extras para roteamento dinâmico. O sistema de avaliação baseado em prioridades fornece um comportamento de roteamento determinístico, facilitando a compreensão e a solução de problemas nas decisões de roteamento.

Para saber mais sobre o roteamento baseado em cabeçalhos do API Gateway, consulte a documentação do serviço.

Para saber mais sobre arquiteturas sem servidor, consulte Serverless Land.

Este conteúdo foi traduzido da postagem original do blog, que pode ser encontrada aqui.

Autores

	Anton Aleksandrov é arquiteto de soluções principal para Serverless na HAQM Web Services (AWS).
	Giedrius Praspaliauskas é Arquiteto de soluções senior de Serverless na HAQM Web Services (AWS).

Tradutor

Daniel Abib é Arquiteto de Soluções Sênior e Especialista em HAQM Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem. http://www.linkedin.com/in/danielabib/

Revisor

Rodrigo Peres é Arquiteto de Soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados