feat(apigatewayv2): http api - custom domain & stage mapping

packages/@aws-cdk/aws-apigatewayv2/README.md

@@ -21,6 +21,7 @@
   - [Defining HTTP APIs](#defining-http-apis)
   - [Cross Origin Resource Sharing (CORS)](#cross-origin-resource-sharing-cors)
   - [Publishing HTTP APIs](#publishing-http-apis)
+  - [Custom Domain](#custom-domain)
 
 ## Introduction
 
@@ -134,3 +135,67 @@ If you omit the `stageName` will create a `$default` stage. A `$default` stage i
 the API's URL - `https://{api_id}.execute-api.{region}.amazonaws.com/`.
 
 Note that, `HttpApi` will always creates a `$default` stage, unless the `createDefaultStage` property is unset.
+
+
+
+### Custom Domain Name
+
+Custom domain names are simpler and more intuitive URLs that you can provide to your API users. Custom domains name are associated to API stages.
+
+The code snippet below creates a custom domain and configures a default domain mapping for your API that maps the
+custom domain to the `$default` stage of the API.
+
+```ts
+const certArn = 'arn:aws:acm:us-east-1:111111111111:certificate';
+const domainName = 'example.com';
+
+const dn = new DomainName(stack, 'DN', {
+  domainName,
+  certificate: acm.Certificate.fromCertificateArn(stack, 'cert', certArn),
+});
+
+const api = new HttpApi(stack, 'HttpProxyProdApi', {
+  defaultIntegration: new LambdaProxyIntegration({ handler }),
+  // https://${dn.domainName} goes to prodApi $default stage
+  defaultDomainMapping: {
+    domainName: dn,
+  },
+});
+```
+
+To associate a specifc `Stage` to a custom domain mapping -
+
+```ts
+api.addStage('beta', {
+  stageName: 'beta',
+  autoDeploy: true,
+  // https://${dn.domainName}/beta goes to prodApi beta stage
+  domainMapping: {
+    domainName: dn,
+    mappingKey: 'beta',
+  },
+} );
+```
+
+The same domain name can be associated with stages across different `HttpApi` as so -
+
+```ts
+const apiDemo = new HttpApi(stack, 'DemoApi', {
+  defaultIntegration: new LambdaProxyIntegration({ handler }),
+  // https://${dn.domainName}/demo goes to apiDemo $default stage
+  defaultDomainMapping: {
+    domainName: dn,
+    mappingKey: 'demo',
+  },
+});
+```
+
+The optional `mappingKey` determines the `path` of the URL with the custom domain. Each custom domain is only allowed
+to have one API mapping with empty `mappingKey`. In the sample above, the custom domain is associated with 3 API
+mapping resources across different APIs and Stages.
+
+|        API     |     Stage   |   URL  |
+| :------------: | :---------: | :----: |
+| api | $default  |   `https://${domainName}`  |
+| api | beta  |   `https://${domainName}/beta`  |
+| apiDemo | $default  |   `https://${domainName}/demo`  |

packages/@aws-cdk/aws-apigatewayv2/lib/common/api-mapping.ts

@@ -0,0 +1,13 @@
+import { IResource } from '@aws-cdk/core';
+
+/**
+ * Represents an ApiGatewayV2 ApiMapping resource
+ * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-apimapping.html
+ */
+export interface IApiMapping extends IResource {
+  /**
+   * ID of the api mapping
+   * @attribute
+   */
+  readonly apiMappingId: string;
+}

packages/@aws-cdk/aws-apigatewayv2/lib/common/domain-name.ts

@@ -0,0 +1,158 @@
+import { ICertificate } from '@aws-cdk/aws-certificatemanager';
+import { Construct, IResource, Resource } from '@aws-cdk/core';
+import { CfnDomainName, CfnDomainNameProps } from '../apigatewayv2.generated';
+import { IStage } from './stage';
+
+/**
+ * Represents an APIGatewayV2 DomainName
+ * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-domainname.html
+ */
+export interface IDomainName extends IResource {
+  /**
+   * The custom domain name
+   *
+   * @attribute
+   *
+   */
+  readonly domainName: string;
+
+  /**
+   * The domain name associated with the regional endpoint for this custom domain name.
+   *
+   * @attribute
+   */
+  readonly regionalDomainName: string;
+
+  /**
+   * The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint.
+   *
+   * @attribute
+   */
+  readonly regionalHostedZoneId: string;
+}
+
+/**
+ * custom domain name attributes
+ */
+export interface DomainNameAttributes {
+  /**
+   * domain name string
+   */
+  readonly domainName: string;
+
+  /**
+   * The domain name associated with the regional endpoint for this custom domain name.
+   */
+  readonly regionalDomainName: string;
+
+  /**
+   * The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint.
+   */
+  readonly regionalHostedZoneId: string;
+}
+
+/**
+ * Options for defaultDomainMapping
+ */
+export interface DefaultDomainMappingOptions {
+  /**
+   * The domain name for the mapping
+   *
+   */
+  readonly domainName: IDomainName;
+
+  /**
+   * The API mapping key
+   *
+   * @default - empty key
+   */
+  readonly mappingKey?: string;
+
+}
+
+/**
+ * Options for DomainMapping
+ */
+export interface DomainMappingOptions extends DefaultDomainMappingOptions {
+  /**
+   * The API Stage
+   *
+   * @default - the $default stage
+   */
+  readonly stage?: IStage;
+}
+
+/**
+ * properties used for creating the DomainName
+ */
+export interface DomainNameProps {
+  /**
+   * The custom domain name
+   */
+  readonly domainName: string;
+  /**
+   * The ACM certificate for this domain name
+   */
+  readonly certificate: ICertificate;
+}
+
+/**
+ * Custom domain resource for the API
+ */
+export class DomainName extends Resource implements IDomainName {
+  /**
+   * import from attributes
+   */
+  public static fromDomainNameAttributes(scope: Construct, id: string, attrs: DomainNameAttributes): IDomainName {
+    class Import extends Resource implements IDomainName {
+      public readonly regionalDomainName = attrs.regionalDomainName;
+      public readonly regionalHostedZoneId = attrs.regionalHostedZoneId;
+      public readonly domainName = attrs.domainName;
+    }
+    return new Import(scope, id);
+  }
+
+  /**
+   * the logical ID of the domain name
+   *
+   * @attribute
+   */
+  public readonly domainNameId: string;
+
+  /**
+   * The custom domain name for your API in Amazon API Gateway.
+   *
+   * @attribute
+   */
+  public readonly domainName: string;
+
+  /**
+   * The domain name associated with the regional endpoint for this custom domain name.
+   */
+  public readonly regionalDomainName: string;
+
+  /**
+   * The region-specific Amazon Route 53 Hosted Zone ID of the regional endpoint.
+   */
+  public readonly regionalHostedZoneId: string;
+
+  constructor(scope: Construct, id: string, props: DomainNameProps) {
+    super(scope, id);
+
+    this.domainName = props.domainName;
+
+    const domainNameProps: CfnDomainNameProps = {
+      domainName: props.domainName,
+      domainNameConfigurations: [
+        {
+          certificateArn: props.certificate.certificateArn,
+          endpointType: 'REGIONAL',
+        },
+      ],
+    };
+    const resource = new CfnDomainName(this, 'Resource', domainNameProps);
+    this.domainNameId = resource.ref;
+    this.regionalDomainName = resource.getAtt('RegionalDomainName').toString();
+    this.regionalHostedZoneId = resource.getAtt('RegionalHostedZoneId').toString();
+  }
+}

packages/@aws-cdk/aws-apigatewayv2/lib/common/index.ts

@@ -1,3 +1,5 @@
 export * from './integration';
 export * from './route';
-export * from './stage';
+export * from './stage';
+export * from './domain-name';
+export * from './api-mapping';

packages/@aws-cdk/aws-apigatewayv2/lib/http/api-mapping.ts

@@ -0,0 +1,92 @@
+import { Construct, Resource } from '@aws-cdk/core';
+import { CfnApiMapping, CfnApiMappingProps } from '../apigatewayv2.generated';
+import { IApiMapping, IDomainName } from '../common';
+import { IHttpApi } from '../http/api';
+import { IHttpStage } from './stage';
+
+/**
+ * Properties used to create the HttpApiMapping resource
+ */
+export interface HttpApiMappingProps {
+  /**
+   * Api mapping name
+   * @default -  logical id
+   */
+  readonly apiMappingName?: string;
+
+  /**
+   * Api mapping key
+   * @default -  empty api mapping key
+   */
+  readonly apiMappingKey?: string;
+
+  /**
+   * The HttpApi to which this mapping is applied
+   */
+  readonly api: IHttpApi;
+
+  /**
+   * custom domain name of the mapping target
+   */
+  readonly domainName: IDomainName;
+
+  /**
+   * stage for the HttpApiMapping resource
+   *
+   * @default - the $default stage
+   */
+  readonly stage?: IHttpStage;
+}
+
+/**
+ * The attributes used to import existing HttpApiMapping
+ */
+export interface HttpApiMappingAttributes {
+  /**
+   * The API mapping ID
+   */
+  readonly apiMappingId: string;
+}
+
+/**
+ * Create a new API mapping for API Gateway HTTP API endpoint.
+ * @resource AWS::ApiGatewayV2::ApiMapping
+ */
+export class HttpApiMapping extends Resource implements IApiMapping {
+  /**
+   * import from API ID
+   */
+  public static fromHttpApiMappingAttributes(scope: Construct, id: string, attrs: HttpApiMappingAttributes): IApiMapping {
+    class Import extends Resource implements IApiMapping {
+      public readonly apiMappingId = attrs.apiMappingId;
+    }
+    return new Import(scope, id);
+  }
+  /**
+   * ID of the API Mapping
+   */
+  public readonly apiMappingId: string;
+
+  /**
+   * Name of the API Mapping
+   * @attribute
+   */
+  public readonly apiMappingName: string;
+
+  constructor(scope: Construct, id: string, props: HttpApiMappingProps) {
+    super(scope, id);
+
+    this.apiMappingName = props.apiMappingName ?? id;
+
+    const apiMappingProps: CfnApiMappingProps = {
+      apiId: props.api.httpApiId,
+      domainName: props.domainName.domainName,
+      stage: props.stage ? props.stage.stageName : '$default',
+      apiMappingKey: props.apiMappingKey,
+    };
+
+    const resource = new CfnApiMapping(this, 'Resource', apiMappingProps);
+    this.apiMappingId = resource.ref;
+  }
+
+}