How to prevent CDK from creating default base path mapping for new DomainName

Question

When you create a CustomDomain while creating a RestApi OR you .addDomainName after creating the RestApi in CDK, a default base path mapping is created for the specified stage to the root of the domain.

I don't want that to be created. I want to create my own base path mapping. When I add one via domain.addBasePathMapping(), I end up with both a mapping to the root and a mapping to the specified base path. Like so:

• api: example.com / stage: dev / path: (none) // don't want this one.
• api: example.com / stage: dev / path: the-base-path //want this one.

Is there a way to either change the default base path mapping OR prevent it from being created?

Code reproduces the issue:

const apiSpec = <openapi spec loaded here>
const zone = route53.HostedZone.fromLookup(this, 'theZone', {
    domainName: 'example.com'
  });
  //Get the existing certificate
  const acmCertificate = acm.Certificate.fromCertificateArn(this, 'Certificate', CERTIFICATE_ARN);

  const apiDomainName = 'example.com';
  const theApi = new apigateway.SpecRestApi(this, `the-example-api`, {
    deploy: true,
    restApiName: 'ApiNameHere',
    deployOptions: {
       stageName: 'dev',
    },
    endpointTypes: [ apigateway.EndpointType.REGIONAL ],
    apiDefinition: apigateway.ApiDefinition.fromInline(apiSpec),
    endpointExportName: `endpointExportName`,
    domainName: {
      domainName: apiDomainName,
      certificate: acmCertificate,
      securityPolicy: apigateway.SecurityPolicy.TLS_1_2
    }
  });
  const domain = theApi.domainName
  domain.addBasePathMapping(theApi, {basePath: 'the-base-path', stage: theApi.deploymentStage});

  //Create alias record to route to apis
  const aRecord = new route53.ARecord(this, 'alias-record', {
    recordName: apiDomainName,
    zone, 
    target: route53.RecordTarget.fromAlias(new targets.ApiGateway(theApi))
  });

Answer 1

Looks like this was a bug that someone had reported in this github issue. It has since been fixed. Now, when you create an api, you can add basePath as an option to the DomainNameOptions, preventing it from creating two separate mappings. E.g.

  const theApi = new apigateway.SpecRestApi(this, `the-example-api`, {
    ...
    ...
    domainName: {
      domainName: apiDomainName,
      certificate: acmCertificate,
      securityPolicy: apigateway.SecurityPolicy.TLS_1_2,
      basePath: 'the-base-path'
    }
  });

Answer 2

The addDomainName method on BaseRestApi always uses the restApi object as the mapping parameter as seen here: https://github.com/aws/aws-cdk/blob/b3a7d5ba67bec09e422c0c843d7dee4653fe9aec/packages/%40aws-cdk/aws-apigateway/lib/restapi.ts#L346-L355

If you don't want that, don't provide the domainName parameter when creating the api and instead create it separate like this:

const domain = new apigateway.DomainName(theApi, 'CustomDomain', {
    domainName: apiDomainName,
    certificate: acmCertificate,
    securityPolicy: apigateway.SecurityPolicy.TLS_1_2
});
domain.addBasePathMapping(theApi, {basePath: 'the-base-path', stage: theApi.deploymentStage});