feat(apigateway): added L2 construct support for Routing Rules on custom domain names

[jasdeepbhalla]

Issue # (if applicable)

Closes #36917.

Reason for this change

API Gateway supports routing rules on custom domain names to route traffic by path and/or header to different REST APIs. The DomainName L2 construct only exposed base path mappings and API mappings; using routing rules required dropping to L1 (CfnRoutingRule), manually building domain name ARNs, and losing synth-time validation. This change adds L2 support so routing rules can be defined with a type-safe API and validated at synth time.

Description of changes

• RoutingMode enum
  BASE_PATH_MAPPING_ONLY (default), ROUTING_RULE_ONLY, and ROUTING_RULE_THEN_API_MAPPING to control how the domain routes traffic (mappings only, routing rules only, or rules then mappings).

• DomainName

  • New optional routingMode prop; passed through to CfnDomainName.
  • When routingMode is ROUTING_RULE_ONLY or ROUTING_RULE_THEN_API_MAPPING, addRoutingRule() is allowed and addBasePathMapping / addApiMapping are disallowed when mode is ROUTING_RULE_ONLY (and vice versa), with clear errors.
  • Routing rules are only supported for REGIONAL endpoints; constructor and addRoutingRule() enforce this.
  • addRoutingRule(id, options) creates a routing rule with priority, conditions (base paths and/or headers), and action (restApi, optional stage, optional stripBasePath).

• RoutingRule L2 construct
  Wraps AWS::ApiGatewayV2::RoutingRule with:

  • Conditions: basePaths?: string[] and/or headers?: { header, valueGlob }[] (AND between path and headers).
  • Action: restApi, optional stage (defaults to API deployment stage), optional stripBasePath.
  • Synth-time validation: priority 0–999999, header name length/pattern, valueGlob length, at most 2 header conditions.
  • Can be used standalone with domainName: IDomainNameRef for cross-stack or imported domains.

• AddRoutingRuleOptions interface
  Named type for addRoutingRule() options (priority, conditions, action) for JSII compatibility.

• README
  New “Custom domain routing rules” subsection under Custom Domains with examples for addRoutingRule() and standalone RoutingRule.

• Integration test
  Domain name made unique per stack (api-${stackName}.example.com) to avoid “domain already exists” conflicts on re-runs.

Describe any new or updated permissions being added

None. The change only defines new L2 constructs that create existing CloudFormation resources (AWS::ApiGateway::DomainName with RoutingMode, AWS::ApiGatewayV2::RoutingRule). No new APIs or IAM permissions are introduced.

Description of how you validated changes

• Unit tests

  • test/routing-rule.test.ts: path-only, header-only, and combined path+header conditions; standalone RoutingRule with imported domain; validation for priority range, header length, and max 2 header conditions.
  • test/domains.test.ts: routingMode on Cfn; addRoutingRule rejected when BASE_PATH_MAPPING_ONLY; addBasePathMapping/addApiMapping rejected when ROUTING_RULE_ONLY; no mapping when ROUTING_RULE_ONLY; REGIONAL-only; and “addRoutingRule creates rule and uses domain ARN”.

• Integration test
  integ.routing-rules.ts: stack with domain in ROUTING_RULE_ONLY, path-based rule, header-based rule, and catch-all rule; domain name made unique per stack to avoid “domain already exists” on re-runs.

• Build/lint
  yarn build and lint pass (import order, indentation, JSII, TS6133 addressed).

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.