feat: introduce reference interfaces, but don't require them yet

This introduces the `IXxxRef` interfaces from #35032, without actually having the L2s extend them yet.

This avoids introducing the implementation burden of them to the L2 interfaces, but does allow pre-implementation in advance of their requirement.

Author: rix0rrr

packages/@aws-cdk/aws-ec2-alpha/lib/subnet-v2.ts

@@ -6,6 +6,7 @@ import { CidrBlock, CidrBlockIpv6, defaultSubnetName } from './util';
 import { RouteTable } from './route';
 import { addConstructMetadata, MethodMetadata } from 'aws-cdk-lib/core/lib/metadata-resource';
 import { propertyInjectable } from 'aws-cdk-lib/core/lib/prop-injectable';
+import { SubnetReference } from 'aws-cdk-lib/aws-ec2/lib/ec2.generated';
 
 /**
  * Interface to define subnet CIDR
@@ -194,6 +195,12 @@ export class SubnetV2 extends Resource implements ISubnetV2 {
        */
       public readonly routeTable: IRouteTable = { routeTableId: attrs.routeTableId! };
 
+      public get subnetRef(): SubnetReference {
+        return {
+          subnetId: this.subnetId,
+        };
+      }
+
       /**
        * Associate a Network ACL with this subnet
        * Required here since it is implemented in the ISubnetV2
@@ -245,6 +252,12 @@ export class SubnetV2 extends Resource implements ISubnetV2 {
    */
   public readonly ipv6CidrBlock?: string;
 
+  public get subnetRef(): SubnetReference {
+    return {
+      subnetId: this.subnetId,
+    };
+  }
+
   /**
    * The type of subnet (public or private) that this subnet represents.
    * @attribute SubnetType

packages/@aws-cdk/aws-ec2-alpha/lib/vpc-v2-base.ts

@@ -6,6 +6,7 @@ import { EgressOnlyInternetGateway, InternetGateway, NatConnectivityType, NatGat
 import { ISubnetV2 } from './subnet-v2';
 import { AccountPrincipal, Effect, PolicyStatement, Role } from 'aws-cdk-lib/aws-iam';
 import { IVPCCidrBlock } from './vpc-v2';
+import { VPCReference } from 'aws-cdk-lib/aws-ec2/lib/ec2.generated';
 
 /**
  * Options to define EgressOnlyInternetGateway for VPC
@@ -327,6 +328,12 @@ export abstract class VpcV2Base extends Resource implements IVpcV2 {
     };
   }
 
+  public get vpcRef(): VPCReference {
+    return {
+      vpcId: this.vpcId,
+    };
+  }
+
   /**
    * Adds a VPN Gateway to this VPC
    * @deprecated use enableVpnGatewayV2 for compatibility with VPCV2.Route

packages/aws-cdk-lib/aws-apigateway/lib/api-key.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { CfnApiKey } from './apigateway.generated';
+import { ApiKeyReference, CfnApiKey, IApiKeyRef } from './apigateway.generated';
 import { ResourceOptions } from './resource';
 import { IRestApi } from './restapi';
 import { IStage } from './stage';
@@ -14,7 +14,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
  * API keys are alphanumeric string values that you distribute to
  * app developer customers to grant access to your API
  */
-export interface IApiKey extends IResourceBase {
+export interface IApiKey extends IResourceBase, IApiKeyRef {
   /**
    * The API key ID.
    * @attribute
@@ -138,6 +138,12 @@ abstract class ApiKeyBase extends Resource implements IApiKey {
       resourceArns: [this.keyArn],
     });
   }
+
+  public get apiKeyRef(): ApiKeyReference {
+    return {
+      apiKeyId: this.keyId,
+    };
+  }
 }
 
 /**

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

@@ -1,12 +1,12 @@
 import { Construct } from 'constructs';
-import { CfnDomainName } from './apigateway.generated';
+import { CfnDomainName, DomainNameReference, IDomainNameRef } from './apigateway.generated';
 import { BasePathMapping, BasePathMappingOptions } from './base-path-mapping';
 import { EndpointType, IRestApi } from './restapi';
 import { IStage } from './stage';
 import * as apigwv2 from '../../aws-apigatewayv2';
 import * as acm from '../../aws-certificatemanager';
 import { IBucket } from '../../aws-s3';
-import { IResource, Names, Resource, Token } from '../../core';
+import { Arn, IResource, Names, Resource, Stack, Token } from '../../core';
 import { ValidationError } from '../../core/lib/errors';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
@@ -94,7 +94,7 @@ export interface DomainNameProps extends DomainNameOptions {
   readonly mapping?: IRestApi;
 }
 
-export interface IDomainName extends IResource {
+export interface IDomainName extends IResource, IDomainNameRef {
   /**
    * The domain name (e.g. `example.com`)
    *
@@ -132,12 +132,22 @@ export class DomainName extends Resource implements IDomainName {
       public readonly domainName = attrs.domainName;
       public readonly domainNameAliasDomainName = attrs.domainNameAliasTarget;
       public readonly domainNameAliasHostedZoneId = attrs.domainNameAliasHostedZoneId;
+
+      public readonly domainNameRef = {
+        domainName: this.domainName,
+        domainNameArn: Arn.format({
+          service: 'apigateway',
+          resource: 'domainnames',
+          resourceName: attrs.domainName,
+        }, Stack.of(scope)),
+      };
     }
 
     return new Import(scope, id);
   }
 
   public readonly domainName: string;
+  public readonly domainNameRef: DomainNameReference;
   public readonly domainNameAliasDomainName: string;
   public readonly domainNameAliasHostedZoneId: string;
   private readonly basePaths = new Set<string | undefined>();
@@ -168,6 +178,7 @@ export class DomainName extends Resource implements IDomainName {
     });
 
     this.domainName = resource.ref;
+    this.domainNameRef = resource.domainNameRef;
 
     this.domainNameAliasDomainName = edge
       ? resource.attrDistributionDomainName

packages/aws-cdk-lib/aws-apigateway/lib/gateway-response.ts

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { CfnGatewayResponse, CfnGatewayResponseProps } from './apigateway.generated';
+import { CfnGatewayResponse, CfnGatewayResponseProps, GatewayResponseReference, IGatewayResponseRef } from './apigateway.generated';
 import { IRestApi } from './restapi';
 import { IResource, Resource } from '../../core';
 import { addConstructMetadata } from '../../core/lib/metadata-resource';
@@ -8,7 +8,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
 /**
  * Represents gateway response resource.
  */
-export interface IGatewayResponse extends IResource {
+export interface IGatewayResponse extends IResource, IGatewayResponseRef {
 }
 
 /**
@@ -61,6 +61,20 @@ export class GatewayResponse extends Resource implements IGatewayResponse {
   /** Uniquely identifies this class. */
   public static readonly PROPERTY_INJECTION_ID: string = 'aws-cdk-lib.aws-apigateway.GatewayResponse';
 
+  /**
+   * Reference an existing GatewayResponse given a gateway response ID.
+   */
+  public static fromGatewayResponseId(scope: Construct, id: string, gatewayResponseId: string): IGatewayResponse {
+    class Import extends Resource implements IGatewayResponse {
+      public readonly gatewayResponseRef = {
+        gatewayResponseId: gatewayResponseId,
+      };
+    }
+    return new Import(scope, id);
+  }
+
+  public readonly gatewayResponseRef: GatewayResponseReference;
+
   constructor(scope: Construct, id: string, props: GatewayResponseProps) {
     super(scope, id);
     // Enhanced CDK Analytics Telemetry
@@ -86,6 +100,7 @@ export class GatewayResponse extends Resource implements IGatewayResponse {
       });
     }
 
+    this.gatewayResponseRef = resource.gatewayResponseRef;
     this.node.defaultChild = resource;
   }
 

packages/aws-cdk-lib/aws-apigateway/lib/resource.ts

@@ -1,16 +1,16 @@
 import { Construct } from 'constructs';
-import { CfnResource, CfnResourceProps } from './apigateway.generated';
+import { CfnResource, CfnResourceProps, IResourceRef, ResourceReference } from './apigateway.generated';
 import { Cors, CorsOptions } from './cors';
 import { Integration } from './integration';
 import { MockIntegration } from './integrations';
-import { Method, MethodOptions, AuthorizationType } from './method';
+import { AuthorizationType, Method, MethodOptions } from './method';
 import { IRestApi, RestApi } from './restapi';
 import { IResource as IResourceBase, Resource as ResourceConstruct } from '../../core';
 import { ValidationError } from '../../core/lib/errors';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
 
-export interface IResource extends IResourceBase {
+export interface IResource extends IResourceBase, IResourceRef {
   /**
    * The parent of this resource or undefined for the root resource.
    */
@@ -383,6 +383,13 @@ export abstract class ResourceBase extends ResourceConstruct implements IResourc
   public get url(): string {
     return this.restApi.urlForPath(this.path);
   }
+
+  public get resourceRef(): ResourceReference {
+    return {
+      resourceId: this.resourceId,
+      restApiId: this.api.restApiId,
+    };
+  }
 }
 
 /**

packages/aws-cdk-lib/aws-apigateway/lib/restapi.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { ApiDefinition } from './api-definition';
 import { ApiKey, ApiKeyOptions, IApiKey } from './api-key';
 import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
-import { CfnAccount, CfnRestApi } from './apigateway.generated';
+import { CfnAccount, CfnRestApi, IRestApiRef, RestApiReference } from './apigateway.generated';
 import { CorsOptions } from './cors';
 import { Deployment } from './deployment';
 import { DomainName, DomainNameOptions } from './domain-name';
@@ -27,7 +27,7 @@ import { APIGATEWAY_DISABLE_CLOUDWATCH_ROLE } from '../../cx-api';
 const RESTAPI_SYMBOL = Symbol.for('@aws-cdk/aws-apigateway.RestApiBase');
 const APIGATEWAY_RESTAPI_SYMBOL = Symbol.for('@aws-cdk/aws-apigateway.RestApi');
 
-export interface IRestApi extends IResourceBase {
+export interface IRestApi extends IResourceBase, IRestApiRef {
   /**
    * The ID of this API Gateway RestApi.
    * @attribute
@@ -738,6 +738,12 @@ export abstract class RestApiBase extends Resource implements IRestApi, iam.IRes
       ...props,
     }).attachTo(this);
   }
+
+  public get restApiRef(): RestApiReference {
+    return {
+      restApiId: this.restApiId,
+    };
+  }
 }
 
 /**

packages/aws-cdk-lib/aws-apigateway/lib/stage.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { AccessLogFormat, IAccessLogDestination } from './access-log';
 import { IApiKey, ApiKeyOptions, ApiKey } from './api-key';
 import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
-import { CfnStage } from './apigateway.generated';
+import { CfnStage, IStageRef, StageReference } from './apigateway.generated';
 import { Deployment } from './deployment';
 import { IRestApi, RestApiBase } from './restapi';
 import { parseMethodOptionsPath } from './util';
@@ -15,7 +15,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
 /**
  * Represents an APIGateway Stage.
  */
-export interface IStage extends IResource {
+export interface IStage extends IResource, IStageRef {
   /**
    * Name of this stage.
    * @attribute
@@ -357,6 +357,13 @@ export abstract class StageBase extends Resource implements IStage {
       ...props,
     }).attachTo(this);
   }
+
+  public get stageRef(): StageReference {
+    return {
+      stageName: this.stageName,
+      restApiId: this.restApi.restApiId,
+    };
+  }
 }
 
 @propertyInjectable

packages/aws-cdk-lib/aws-apigateway/lib/usage-plan.ts

@@ -1,6 +1,6 @@
 import { Construct } from 'constructs';
 import { IApiKey } from './api-key';
-import { CfnUsagePlan, CfnUsagePlanKey } from './apigateway.generated';
+import { CfnUsagePlan, CfnUsagePlanKey, IUsagePlanRef, UsagePlanReference } from './apigateway.generated';
 import { Method } from './method';
 import { IRestApi } from './restapi';
 import { Stage } from './stage';
@@ -161,7 +161,7 @@ export interface AddApiKeyOptions {
 /**
  * A UsagePlan, either managed by this CDK app, or imported.
  */
-export interface IUsagePlan extends IResource {
+export interface IUsagePlan extends IResource, IUsagePlanRef {
   /**
    * Id of the usage plan
    * @attribute
@@ -211,6 +211,12 @@ abstract class UsagePlanBase extends Resource implements IUsagePlan {
       resource.overrideLogicalId(options?.overrideLogicalId);
     }
   }
+
+  public get usagePlanRef(): UsagePlanReference {
+    return {
+      usagePlanId: this.usagePlanId,
+    };
+  }
 }
 
 @propertyInjectable

packages/aws-cdk-lib/aws-apigateway/lib/vpc-link.ts

@@ -8,7 +8,7 @@ import { propertyInjectable } from '../../core/lib/prop-injectable';
 /**
  * Represents an API Gateway VpcLink
  */
-export interface IVpcLink extends IResource {
+export interface IVpcLink extends IResource, IVpcLinkRef {
   /**
    * Physical ID of the VpcLink resource
    * @attribute
@@ -56,6 +56,9 @@ export class VpcLink extends Resource implements IVpcLink {
   public static fromVpcLinkId(scope: Construct, id: string, vpcLinkId: string): IVpcLink {
     class Import extends Resource implements IVpcLink {
       public vpcLinkId = vpcLinkId;
+      public vpcLinkRef = {
+        vpcLinkId: vpcLinkId,
+      };
     }
 
     return new Import(scope, id);
@@ -67,6 +70,8 @@ export class VpcLink extends Resource implements IVpcLink {
    */
   public readonly vpcLinkId: string;
 
+  public readonly vpcLinkRef: VpcLinkReference;
+
   private readonly _targets = new Array<elbv2.INetworkLoadBalancer>();
 
   constructor(scope: Construct, id: string, props: VpcLinkProps = {}) {
@@ -83,6 +88,7 @@ export class VpcLink extends Resource implements IVpcLink {
       targetArns: Lazy.list({ produce: () => this.renderTargets() }),
     });
 
+    this.vpcLinkRef = cfnResource.vpcLinkRef;
     this.vpcLinkId = cfnResource.ref;
 
     if (props.targets) {