AWS recently introduced a new capability for Amazon API Gateway featuring dynamic routing rules for custom domain names – allowing users to route API requests based on HTTP header values, either independently or in combination with URL paths.
Earlier, developers relying on API Gateway for dynamic routing often resorted to different URL paths, such as /v1/products and /v2/products, to segment traffic. However, this approach, although functional, may lead to complex URL structures and an increase in API endpoints. Yet, with the new dynamic routing rules feature, users can make routing decisions directly within custom domain name settings, simply by configuring a custom domain name – thus allowing routing decisions to be based on incoming HTTP headers, base paths, or a combination of both.
Additionally, with this feature, users don’t need to alter or create new paths for API transitions, providing a smoother path for API versioning and A/B testing. Furthermore, it also unlocks dynamic backend selection based on criteria like hostname, tenant ID, or even cookie values, allowing for fine-grained control over API traffic without the need for additional proxy layers.
(Source: AWS Compute blog post)
At its core, an API Gateway routing rule functions as a specific resource tied to a custom domain, dictating how incoming requests are forwarded. Each rule is defined by three critical properties: Conditions, which specify criteria based on up to two header and one base path values (all must be met, with wildcards supported for flexible matching); Actions, which define the API stage to be invoked upon a match; and Priority, determining the evaluation order. For instance, a header condition like x-version can use wildcards such as *v2* to match x-version=alpha-v2-latest or x-version=beta-v2-test, enabling nuanced routing strategies.
Before creating routing rules, users need at least one API, stage, and custom domain name. There are three routing modes: “API mappings only,” which uses base path mappings without Routing Rules; “Routing rules then API mappings,” where Routing Rules take precedence and unmatched requests fall back to base path mappings; and “Routing rules only,” the recommended mode that relies solely on Routing Rules, ideal for new domains or after transitioning from API mappings. Always test changes in non-production environments before switching to production, as existing mappings will be overwritten.
While dynamic routing capabilities for API versioning and A/B testing exist in other major cloud API management platforms, such as Azure API Management and Google Apigee, their implementations typically rely on policy expressions or proxy-level configurations. Amazon API Gateway’s new approach distinguishes itself by offering a dedicated, declarative routing rule resource directly at the custom domain level, aiming to simplify these specific routing scenarios.
Furthermore, API Gateway offers visibility into request processing through access logging. Each request now includes context variables that clarify routing decisions, such as the $context.customDomain.routingRuleIdMatched, which indicates the matched rule. Other variables like $context.domainName, $context.apiId, and $context.Stage provides the full routing context. Analyzing these logs allows users to verify routing behavior, troubleshoot issues, and gain insights into traffic patterns across API versions or test variants.
In a Medium blog post, a software engineer, Paul Issack Minoltan, concluded:
In essence, the new routing rules in API Gateway allow you to move sophisticated routing logic directly into your API Gateway configuration, streamlining your architecture and providing more control over how your API traffic is directed.
Lastly, more information can be found in the service documentation, and an end-to-end example for the feature is available on GitHub.
