feat(apigateway): add option to set the base path when adding a domain name to a Rest API (#17915)

If a domain name has an empty base path mapping, API Gateway does not allow the
creation of additional base path mappings. The problem is that `addDomainName`
always creates an empty base path mapping, preventing users to add their own
afterwards. 

Add a property to define a base path mapping at the same time as adding the
domain name.

Fixes #9581.


----

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

Author: otaviomacedo

packages/@aws-cdk/aws-apigateway/lib/domain-name.ts

@@ -48,6 +48,16 @@ export interface DomainNameOptions {
    * @default - mTLS is not configured.
    */
   readonly mtls?: MTLSConfig;
+
+  /**
+   * The base path name that callers of the API must provide in the URL after
+   * the domain name (e.g. `example.com/base-path`). If you specify this
+   * property, it can't be an empty string.
+   *
+   * @default - map requests from the domain root (e.g. `example.com`). If this
+   * is undefined, no additional mappings will be allowed on this domain name.
+   */
+  readonly basePath?: string;
 }
 
 export interface DomainNameProps extends DomainNameOptions {
@@ -104,6 +114,7 @@ export class DomainName extends Resource implements IDomainName {
   public readonly domainName: string;
   public readonly domainNameAliasDomainName: string;
   public readonly domainNameAliasHostedZoneId: string;
+  private readonly basePaths = new Set<string | undefined>();
 
   constructor(scope: Construct, id: string, props: DomainNameProps) {
     super(scope, id);
@@ -136,7 +147,9 @@ export class DomainName extends Resource implements IDomainName {
       : resource.attrRegionalHostedZoneId;
 
     if (props.mapping) {
-      this.addBasePathMapping(props.mapping);
+      this.addBasePathMapping(props.mapping, {
+        basePath: props.basePath,
+      });
     }
   }
 
@@ -146,6 +159,10 @@ export class DomainName extends Resource implements IDomainName {
    * @param options Options for mapping to base path with or without a stage
    */
   public addBasePathMapping(targetApi: IRestApi, options: BasePathMappingOptions = { }) {
+    if (this.basePaths.has(undefined)) {
+      throw new Error('This domain name already has an empty base path. No additional base paths are allowed.');
+    }
+    this.basePaths.add(options.basePath);
     const basePath = options.basePath || '/';
     const id = `Map:${basePath}=>${Names.nodeUniqueId(targetApi.node)}`;
     return new BasePathMapping(this, id, {

packages/@aws-cdk/aws-apigateway/test/domains.test.ts

@@ -259,6 +259,79 @@ describe('domains', () => {
     });
   });
 
+  test('a base path can be defined when adding a domain name', () => {
+    // GIVEN
+    const domainName = 'my.domain.com';
+    const basePath = 'users';
+    const stack = new Stack();
+    const certificate = new acm.Certificate(stack, 'cert', { domainName: 'my.domain.com' });
+
+    // WHEN
+    const api = new apigw.RestApi(stack, 'api', {});
+
+    api.root.addMethod('GET');
+
+    api.addDomainName('domainId', { domainName, certificate, basePath });
+
+    // THEN
+    expect(stack).toHaveResource('AWS::ApiGateway::BasePathMapping', {
+      'BasePath': 'users',
+      'RestApiId': {
+        'Ref': 'apiC8550315',
+      },
+    });
+  });
+
+  test('additional base paths can added if addDomainName was called with a non-empty base path', () => {
+    // GIVEN
+    const domainName = 'my.domain.com';
+    const basePath = 'users';
+    const stack = new Stack();
+    const certificate = new acm.Certificate(stack, 'cert', { domainName: 'my.domain.com' });
+
+    // WHEN
+    const api = new apigw.RestApi(stack, 'api', {});
+
+    api.root.addMethod('GET');
+
+    const dn = api.addDomainName('domainId', { domainName, certificate, basePath });
+    dn.addBasePathMapping(api, {
+      basePath: 'books',
+    });
+
+    // THEN
+    expect(stack).toHaveResource('AWS::ApiGateway::BasePathMapping', {
+      'BasePath': 'users',
+      'RestApiId': {
+        'Ref': 'apiC8550315',
+      },
+    });
+    expect(stack).toHaveResource('AWS::ApiGateway::BasePathMapping', {
+      'BasePath': 'books',
+      'RestApiId': {
+        'Ref': 'apiC8550315',
+      },
+    });
+  });
+
+  test('no additional base paths can added if addDomainName was called without a base path', () => {
+    // GIVEN
+    const domainName = 'my.domain.com';
+    const stack = new Stack();
+    const certificate = new acm.Certificate(stack, 'cert', { domainName: 'my.domain.com' });
+
+    // WHEN
+    const api = new apigw.RestApi(stack, 'api', {});
+
+    api.root.addMethod('GET');
+
+    const dn = api.addDomainName('domainId', { domainName, certificate });
+
+    expect(() => dn.addBasePathMapping(api, { basePath: 'books' }))
+      .toThrow(/No additional base paths are allowed/);
+  });
+
+
   test('domain name cannot contain uppercase letters', () => {
     // GIVEN
     const stack = new Stack();