feat: implement UsagePlan and ApiKey support in L2 constructs for aws-apigatewayv2 (WebSocketApi) #35060

maramure · 2025-07-24T16:39:55Z

Issue # (if applicable)

Reason for this change

Couldn't create UsagePlans and ApiKeys for WebSocketApi (apigatewayv2) using L2 constructs, cause these 2 features were supported only by RestApi (apigatewayv1).

Description of changes

HttpApi(apigatewayv2) doesn't permit creating UsagePlans or ApiKeys in any way, so bringing these functionalities from apigatewayv1 to apigatewayv2 is possible only for WebSocketApi.

Added UsagePlan and ApiKey files in aws-apigatewayv2/lib/websocket folder
Implemented needed interfaces, classes and methods very similar to what was written for RestApi (apigatewayv1)
Included explicit dependency management between components for proper CloudFormation deployment order
Added new JSDoc in order to be able to build the project

Describe any new or updated permissions being added

N/A

Description of how you validated changes

Tested manually by deploying a stack containing and linking the new features
Wrote unit and integration tests

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

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

gasolima · 2025-07-30T10:02:52Z

...es/@aws-cdk-testing/framework-integ/test/aws-apigatewayv2/test/websocket/integ.usage-plan.ts

+
+const webSocketApi = new WebSocketApi(stack, 'WebSocketApi');
+
+webSocketApi.addRoute('$connect', {


What's the reasons for adding routes('$connect', 'sendMessage')?

They were written just to test if addRoute method works. But because I want to test only the usage plan and the routes don't have an impact on this, I deleted them from the integ test.

gasolima · 2025-07-30T10:06:37Z

...es/@aws-cdk-testing/framework-integ/test/aws-apigatewayv2/test/websocket/integ.usage-plan.ts

+const webSocketStage = new WebSocketStage(stack, 'WebSocketStage', {
+  webSocketApi,
+  stageName: 'dev',
+  throttle: {


since we're testing UsagePlan, can we remove all the optional props in other constructor. That will make the code easier to read/understand

Yes, I kept only the mandatory properties for both WebSocketStages.

gasolima · 2025-07-30T10:10:40Z

...es/@aws-cdk-testing/framework-integ/test/aws-apigatewayv2/test/websocket/integ.usage-plan.ts

+
+const apiKey = new ApiKey(stack, 'ApiKey');
+
+const usagePlan = new UsagePlan(stack, 'UsagePlan', {


can we add all the optional parameter? since we want to cover as much branches as possible

Yes, I added both the mandatory and optional parameters for ApiKey and UsagePlan, because these are the 2 new added features.

gasolima · 2025-07-30T10:31:16Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/api-key.ts

+    class Import extends ApiKeyBase {
+      public keyId = apiKeyId;
+      public keyArn = Stack.of(this).formatArn({
+        service: 'apigateway',


Looking at other constructors in apigwv2, i see service: 'execute-api',. Why are we going with apigateway here? also same comment on line 181

Looking here
I saw that 'execute-api' is used only for the endpoints, while the other resources use 'apigateway' no matter if they are apigateway v1 or v2.

gasolima · 2025-07-30T10:32:57Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/api-key.ts

+      public keyId = apiKeyId;
+      public keyArn = Stack.of(this).formatArn({
+        service: 'apigateway',
+        account: '',


why are we going with empty string account? instead of removing the account prop

For a resource's ARN we need the account field empty (as I have seen here). If we would delete the account property, the account would be written by default.

gasolima · 2025-07-30T10:45:40Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+   * @param options options that control the behaviour of this method
+   */
+  public addApiKey(apiKey: IApiKey, options?: AddApiKeyOptions): void {
+    let id: string;


What's the point of having let here? also since it's used one time isn't it better to have

const resource = new CfnUsagePlanKey(this, `${prefix}:${Names.nodeUniqueId(apiKey.node)}`, {`

let is used only if that variable could take more values depending on some conditions. Actually you are right, we don't need let in this case because to the id we assign only one string, no matter what. I modified that part as you suggested.

gasolima · 2025-07-30T10:46:26Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+    addConstructMetadata(this, props);
+    let resource: CfnUsagePlan;
+
+    resource = new CfnUsagePlan(this, 'Resource', {


can we have

const resource = new CfnUsagePlan(this, 'Resource', {

Yes, actually this is the good way of writing. Same explanation as in the previous comment.

gasolima · 2025-07-30T11:14:43Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+    }
+  }
+
+  private renderThrottle(props: ThrottleSettings | undefined): (CfnUsagePlan.ThrottleSettingsProperty | Token) {


This function never returns Token, right? can we remove it?

Yes, this function never return Token, but it is possible to return undefined. I replaced Token with undefined and I adjusted the code so that if the props are undefined, the function would also return undefined.

gasolima · 2025-07-30T11:18:10Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+      validateInteger(limit, 'Throttle quota limit');
+      const ret = {
+        limit: limit ? limit : undefined,
+        offset: props.quota ? props.quota.offset : undefined,


this check not needed, since it's checked in the if L283
the same comment on L291

Yes, they are not necessary. I removed the checks for limit, offset and period.
For example, this is enough: limit: props.quota.limit, because if the limit is undefined it will return undefined which is the desired outcome.

gasolima · 2025-07-30T11:21:46Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+   * @default none
+   * @deprecated use `addApiKey()`
+   */
+  readonly apiKey?: IApiKey;


Why are we adding deprecated field?

I have kept the deprecated field apiKey only because it is kept in apigatewayv1 too. Now, I removed it from the WebSocket's UsagePlan because is not needed.

Why the apiKey property was not useful:

It only allowed adding a single API key to the UsagePlan

Internally, it just called the addApiKey() method anyway

The addApiKey() method provides the same functionality with more flexibility

The better approach:

Use only the addApiKey() method directly, which allows adding multiple keys

Keys can be added after UsagePlan creation, providing more control

This eliminates the deprecated property while maintaining full functionality

gasolima · 2025-07-30T11:25:27Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+  }
+
+  private createStage(apiStage: UsagePlanPerApiStage): CfnUsagePlan.ApiStageProperty {
+    const stage = apiStage.stage ? apiStage.stage.stageName.toString() : undefined;


suggestion: isn't it better to wrap this function with one condition

private createStage(apiStage: UsagePlanPerApiStage): CfnUsagePlan.ApiStageProperty { if(apiStage.stage){ return { stage: apiStage.stage.stageName.toString(), apiId: apiStage.stage.api.apiId } } }

Yes, is much clear in this way. Also, I added the fact that if apiStage.stage is undefined, the method would explicitly return undefined.

gasolima · 2025-07-30T11:26:38Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+  }
+
+  private renderApiStages(apiStages: UsagePlanPerApiStage[] | undefined): CfnUsagePlan.ApiStageProperty[] | undefined {
+    if (apiStages && apiStages.length > 0) {


this condition && apiStages.length > 0 is useless, can we remove it?

It is somehow useful for maintaining the CDK standards.

Without the apiStages.length > 0 condition:

When a user creates a UsagePlan with an empty apiStages array (apiStages: [])

The CloudFormation Template explicitly shows: "ApiStages": []

With the apiStages.length > 0 condition:

Empty arrays are treated as undefined

The ApiStages property is omitted entirely from the CloudFormation Template

This follows CDK's standard practice of omitting optional properties when they have no meaningful values

gasolima · 2025-07-30T11:52:22Z

packages/aws-cdk-lib/aws-apigatewayv2/test/websocket/api-key.test.ts

+      // WHEN
+      new RateLimitedApiKey(stack, 'test-api-key', {
+        customerId: 'test-customer',
+        quota: {


can we pass also throttle and apiStages? to check that we're propagating them correctly

Yes, this would be a better approach. I added throttle and apiStages too.

gasolima · 2025-07-30T12:03:02Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/usage-plan.ts

+        rateLimit: rateLimit,
+      };
+    }
+    return ret!;


non null assertion operator should be avoided unless it's needed

Yes, I modified the code such that all the cases are covered (props are undefined or not) and return ret! is not needed anymore.

aws-cdk-automation · 2025-08-04T17:34:34Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
Commit ID: 596eb12
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

kumsmrit · 2025-08-06T11:31:43Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/api-key.ts

+  /**
+   * Uniquely identifies this class.
+   */
+  public static readonly PROPERTY_INJECTION_ID: string = 'aws-cdk-lib.aws-apigatewayv2.ApiKey';


The PROPERTY_INJECTION_ID should be more specific to avoid conflicts with other similar constructs. Consider changing to:'aws-cdk-lib.aws-apigatewayv2.websocket.ApiKey or aws-cdk-lib.aws-apigatewayv2.WebSocketApiKey. Applicable for other constructs also.

Yes, this implementation follows CDK patterns. I used aws-cdk-lib.aws-apigatewayv2.websocket.ApiKey because it aligns with existing CDK conventions to having clear names for the properties. The alternative approach would have required renaming classes, which would have been an unnecessary refactoring effort.

kumsmrit · 2025-08-06T16:49:08Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/api-key.ts

+
+  /**
+   * The API key ARN.
+   */


Based on the Design guidelines, we should add the @attribute tag for this resource property.

Thank you for the resource you attached. I didn't know this information. I added @attribute tag now.

kumsmrit · 2025-08-06T16:54:18Z

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/api-key.ts

+  /**
+   * A name for the API key. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the API key name.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-name
+   * @default automically generated name


Typo: automically should be automatically.

Corrected it

kumsmrit · 2025-08-06T17:17:50Z

...es/@aws-cdk-testing/framework-integ/test/aws-apigatewayv2/test/websocket/integ.usage-plan.ts

+
+usagePlan.addApiKey(apiKey);
+usagePlan.addApiStage({ api: webSocketApi, stage: webSocketStage2 });
+


Consider adding a RateLimitedApiKey test case as well to the integration test.

Good idea. I added the creation of a new WebsocketStage and a RateLimitedApiKey. It is not needed to do a UsagePlan too, because it is automatically created when a RateLimitedApiKey is created.

mergify · 2025-08-18T20:49:31Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-08-18T20:49:35Z

This pull request has been removed from the queue for the following reason: pull request branch update failed.

The pull request can't be updated.

You should update or rebase your pull request manually. If you do, this pull request will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue, you can requeue the pull request, without updating it, by posting a @mergifyio requeue comment.

Pull request has been modified.

mergify · 2025-08-19T13:35:54Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2025-08-19T14:03:42Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2025-08-19T14:03:58Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

github-actions bot added effort/medium Medium work item – several days of effort feature-request A feature should be added or improved. p2 beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK labels Jul 24, 2025

aws-cdk-automation requested a review from a team July 24, 2025 16:40

aws-cdk-automation previously requested changes Jul 24, 2025

View reviewed changes

maramure marked this pull request as ready for review July 30, 2025 08:25

maramure force-pushed the usageplan branch from 8ef92e9 to 19d431a Compare July 30, 2025 08:30

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Jul 30, 2025

gasolima reviewed Jul 30, 2025

View reviewed changes

github-actions bot mentioned this pull request Aug 1, 2025

Monthly PR metrics report #35128

Closed

maramure force-pushed the usageplan branch 4 times, most recently from 63229eb to 596eb12 Compare August 4, 2025 17:02

kumsmrit reviewed Aug 6, 2025

View reviewed changes

maramure force-pushed the usageplan branch from 596eb12 to 669964a Compare August 12, 2025 17:32

feat(apigwv2): add UsagePlan and ApiKey for WebSocketApi

e8f9d4a

maramure force-pushed the usageplan branch from 669964a to e8f9d4a Compare August 12, 2025 17:36

kumsmrit previously approved these changes Aug 18, 2025

View reviewed changes

Merge branch 'main' into usageplan

53a31e7

kumsmrit approved these changes Aug 19, 2025

View reviewed changes

Merge branch 'main' into usageplan

fde473d

mergify bot merged commit f7faffe into aws:main Aug 19, 2025
18 checks passed

github-actions bot locked as resolved and limited conversation to collaborators Aug 19, 2025


		const webSocketApi = new WebSocketApi(stack, 'WebSocketApi');

		webSocketApi.addRoute('$connect', {


		const apiKey = new ApiKey(stack, 'ApiKey');

		const usagePlan = new UsagePlan(stack, 'UsagePlan', {


		usagePlan.addApiKey(apiKey);
		usagePlan.addApiStage({ api: webSocketApi, stage: webSocketStage2 });

feat: implement UsagePlan and ApiKey support in L2 constructs for aws-apigatewayv2 (WebSocketApi) #35060

feat: implement UsagePlan and ApiKey support in L2 constructs for aws-apigatewayv2 (WebSocketApi) #35060

Uh oh!

Conversation

maramure commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gasolima Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maramure Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aws-cdk-automation commented Aug 4, 2025

AWS CodeBuild CI Report

Uh oh!

maramure commented Jul 24, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

gasolima Jul 30, 2025 •

edited

Loading

maramure Aug 4, 2025 •

edited

Loading