feat(apigateway): support the `mode` propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

tttol · 2025-04-18T07:26:52Z

Issue # (if applicable)

N/A

Reason for this change

AWS::ApiGateway::RestApi has a mode property, but the L2 construct for API Gateway (RestApi class) does not currently expose this property.
Therefore, I added the mode property to the RestApiProps interface.

Description of changes

Introduced an optional mode property in RestApiProps.
Created an enum class RestApiMode to define the possible values for mode. This enum includes two values: merge and overwrite.
Added unit and integration tests.
Updated the README.md for aws-apigateway.

Describe any new or updated permissions being added

No new IAM permissions are introduced.

Description of how you validated changes

packages/aws-cdk-lib/aws-apigateway/test/restapi.test.ts
packages/@aws-cdk-testing/framework-integ/test/aws-apigateway/test/integ.restapi.ts

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.

This reverts commit 6998dbd.

tttol · 2025-04-20T23:25:34Z

I can't resolve CodeCov error...
https://github.com/aws/aws-cdk/actions/runs/14564289548/job/40851338578?pr=34198

Run actions/github-script@v7
Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable
    at OidcClient.<anonymous> (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:585:23)
    at Generator.next (<anonymous>)
    at /home/runner/work/_actions/actions/github-script/v7/dist/index.js:522:71
    at new Promise (<anonymous>)
    at __webpack_modules__.8041.__awaiter (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:518:12)
    at OidcClient.getIDToken (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:571:16)
    at Object.<anonymous> (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:421:46)
    at Generator.next (<anonymous>)
    at /home/runner/work/_actions/actions/github-script/v7/dist/index.js:133:71
    at new Promise (<anonymous>)
Error: Unhandled error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable

go-to-k

Thanks for the PR! Left some minor comments.

go-to-k · 2025-04-21T08:59:25Z

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

+  /**
+   * This property applies only when you use OpenAPI to define your REST API.
+   * The Mode determines how API Gateway handles resource updates.
+   *


Shouldn't this property (mode) be in SpecRestApiProps?

go-to-k · 2025-04-21T09:01:37Z

packages/aws-cdk-lib/aws-apigateway/README.md

+
+----
+
+This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.


Why is this necessary? (The same statement is above.)

Oops, It was a simple mistake.

go-to-k · 2025-04-21T09:04:08Z

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

-export interface RestApiProps extends RestApiOptions {
+export interface RestApiProps extends RestApiBaseProps, ResourceOptions {


This is an appropriate change. However, it may not be the right thing to do with this PR that adds the mode property. As a type, it should be safe since it is compatible with the original type, but we might want to avoid the change just in case in this PR.

go-to-k · 2025-04-21T09:07:20Z

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

+ * Specifies how API Gateway handles resource updates when importing an OpenAPI definition.
+ * This property applies only when you use OpenAPI to define your REST API.
+ */
+export enum RestApiMode {


It would be good to bring it below export enum EndpointType.

go-to-k · 2025-04-21T09:16:51Z

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

+  test('mode property is set correctly', () => {
+    // WHEN
+    const apiWithOverwrite = new apigw.RestApi(stack, 'api-overwrite', {
+      mode: apigw.RestApiMode.OVERWRITE,
+    });
+    apiWithOverwrite.root.addMethod('GET');
+
+    const apiWithMerge = new apigw.RestApi(stack, 'api-merge', {
+      mode: apigw.RestApiMode.MERGE,
+    });
+    apiWithMerge.root.addMethod('GET');
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {
+      Name: 'api-overwrite',
+      Mode: 'overwrite',
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {
+      Name: 'api-merge',
+      Mode: 'merge',
+    });
+  });
+
+  test('mode property is optional', () => {
+    // WHEN
+    const api = new apigw.RestApi(stack, 'api');
+    api.root.addMethod('GET');
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {
+      Name: 'api',
+    });
+    // Mode should not be present in the template when not specified
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {
+      Mode: Match.absent(),
+    });
+  });


We can change like this:

Suggested change

test('mode property is set correctly', () => {

// WHEN

const apiWithOverwrite = new apigw.RestApi(stack, 'api-overwrite', {

mode: apigw.RestApiMode.OVERWRITE,

});

apiWithOverwrite.root.addMethod('GET');

const apiWithMerge = new apigw.RestApi(stack, 'api-merge', {

mode: apigw.RestApiMode.MERGE,

});

apiWithMerge.root.addMethod('GET');

// THEN

Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {

Name: 'api-overwrite',

Mode: 'overwrite',

});

Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {

Name: 'api-merge',

Mode: 'merge',

});

});

test('mode property is optional', () => {

// WHEN

const api = new apigw.RestApi(stack, 'api');

api.root.addMethod('GET');

// THEN

Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {

Name: 'api',

});

// Mode should not be present in the template when not specified

Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {

Mode: Match.absent(),

});

});

test.each([

[apigw.RestApiMode.OVERWRITE, 'overwrite'],

[apigw.RestApiMode.MERGE, 'merge'],

[undefined, undefined],

])('mode property is set (%s)', (mode, expectedMode) => {

// WHEN

const api = new apigw.RestApi(stack, 'api', {

mode,

});

api.root.addMethod('GET');

// THEN

Template.fromStack(stack).hasResourceProperties('AWS::ApiGateway::RestApi', {

Name: 'api',

Mode: expectedMode ?? Match.absent(),

});

});

Thanks for the suggestion!

go-to-k · 2025-04-21T10:10:30Z

I can't resolve CodeCov error...

The PR has been merged, but still seems to have that problem. (I've seen that problem in other PRs as well.)

In this PR, it's good to not worry about it for now.

go-to-k · 2025-04-21T10:19:37Z

packages/aws-cdk-lib/aws-apigateway/README.md

@@ -66,6 +70,24 @@ book.addMethod('GET');
 book.addMethod('DELETE');
 ```

+When using OpenAPI to define your REST API, you can control how API Gateway handles resource updates using the `mode` property. Valid values are:


If this property is applied when using OpenAPI only, it would be good to bring it in the ### OpenAPI Definition, what do you think?

I think so, moved this contents to ## OpenAPI Definition section 🙋🏻‍♂️

aws-cdk-automation

(This review is outdated)

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

aws-cdk-automation · 2025-04-21T22:54:56Z

AWS CodeBuild CI Report

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

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

go-to-k

Thanks for the changes. I'll approve after applying the last comments.

go-to-k · 2025-04-22T03:10:26Z

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

+   * This property applies only when you use OpenAPI to define your REST API.
+   * The Mode determines how API Gateway handles resource updates.


Moving the property to SpecRestApiProps would make this explanation simpler.

Suggested change

* This property applies only when you use OpenAPI to define your REST API.

* The Mode determines how API Gateway handles resource updates.

* The Mode that determines how API Gateway handles resource updates.

go-to-k · 2025-04-22T03:13:45Z

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

+ * Specifies how API Gateway handles resource updates when importing an OpenAPI definition.
+ * This property applies only when you use OpenAPI to define your REST API.


Suggested change

* Specifies how API Gateway handles resource updates when importing an OpenAPI definition.

* This property applies only when you use OpenAPI to define your REST API.

* The Mode that determines how API Gateway handles resource updates when importing an OpenAPI definition.

go-to-k · 2025-04-22T03:14:30Z

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

@@ -275,6 +275,7 @@ export interface RestApiProps extends RestApiOptions {
   * @default - Metering is disabled.
   */
  readonly apiKeySourceType?: ApiKeySourceType;
+


nit.

Suggested change

tttol added 5 commits April 15, 2025 06:12

add mode property

8a90469

add Enum

5815043

add unit test&fix JSDoc

96812eb

update integ test

8547cda

update README

7f0055e

github-actions bot added the repeat-contributor [Pilot] contributed between 3-5 PRs to the CDK label Apr 18, 2025

aws-cdk-automation requested a review from a team April 18, 2025 07:27

github-actions bot added the p2 label Apr 18, 2025

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

tttol added 3 commits April 18, 2025 20:04

Merge branch 'main' into add-restapiprops

08c6be3

update codecov.yml

6998dbd

Revert "update codecov.yml"

bdbf377

This reverts commit 6998dbd.

go-to-k suggested changes Apr 21, 2025

View reviewed changes

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

go-to-k reviewed Apr 21, 2025

View reviewed changes

fix for the pr comment

f25fd80

aws-cdk-automation previously requested changes Apr 21, 2025

View reviewed changes

update integ.spec-restapi.ts

e7c9b0e

tttol added 2 commits April 22, 2025 06:38

chore

3c44a30

rm empty line

086bd6a

go-to-k suggested changes Apr 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(apigateway): support the `mode` propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

feat(apigateway): support the `mode` propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

tttol commented Apr 18, 2025

tttol commented Apr 20, 2025 •

edited

Loading

go-to-k left a comment

go-to-k Apr 21, 2025

go-to-k Apr 21, 2025

tttol Apr 21, 2025 •

edited

Loading

go-to-k Apr 21, 2025

go-to-k Apr 21, 2025

go-to-k Apr 21, 2025 •

edited

Loading

tttol Apr 21, 2025

go-to-k commented Apr 21, 2025 •

edited

Loading

go-to-k Apr 21, 2025

tttol Apr 21, 2025

aws-cdk-automation left a comment •

edited

Loading

aws-cdk-automation commented Apr 21, 2025

go-to-k left a comment

go-to-k Apr 22, 2025

go-to-k Apr 22, 2025

go-to-k Apr 22, 2025


		----

		This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.

		export interface RestApiProps extends RestApiOptions {
		export interface RestApiProps extends RestApiBaseProps, ResourceOptions {

		* This property applies only when you use OpenAPI to define your REST API.
		* The Mode determines how API Gateway handles resource updates.

	* This property applies only when you use OpenAPI to define your REST API.
	* The Mode determines how API Gateway handles resource updates.
	* The Mode that determines how API Gateway handles resource updates.

		* Specifies how API Gateway handles resource updates when importing an OpenAPI definition.
		* This property applies only when you use OpenAPI to define your REST API.

feat(apigateway): support the mode propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

Are you sure you want to change the base?

feat(apigateway): support the mode propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

Conversation

tttol commented Apr 18, 2025

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

tttol commented Apr 20, 2025 • edited Loading

go-to-k left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tttol Apr 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

go-to-k Apr 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

go-to-k commented Apr 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aws-cdk-automation left a comment • edited Loading

Choose a reason for hiding this comment

aws-cdk-automation commented Apr 21, 2025

AWS CodeBuild CI Report

go-to-k left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feat(apigateway): support the `mode` propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

feat(apigateway): support the `mode` propertyfor how API Gateway resources are updated when using an OpenAPI definition #34198

tttol commented Apr 20, 2025 •

edited

Loading

tttol Apr 21, 2025 •

edited

Loading

go-to-k Apr 21, 2025 •

edited

Loading

go-to-k commented Apr 21, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading