feat(apigateway): add `mode` property for `SpecRestApi` #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 (SpecRestApi class) does not currently expose this property.
Therefore, I added the mode property to the SpecRestApiProps interface.

Description of changes

Introduced an optional mode property in SpecRestApiProps.
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.spec-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.

go-to-k

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

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

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

go-to-k

LGTM.

It might be good to simplify the PR title, like: feat(apigateway): add `mode` property for SpecRestApi.

go-to-k

Sorry, There was something I had missed...

go-to-k · 2025-04-22T11:14:52Z

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

+You can control how API Gateway handles resource updates using the `mode` property. Valid values are:
+
+* `overwrite` - The new API definition replaces the existing one. The existing API identifier remains unchanged.
+* `merge` - The new API definition is merged with the existing API.
+
+If you don't specify this property, a default value is chosen:
+* For REST APIs created before March 29, 2021, the default is `overwrite`
+* For REST APIs created after March 29, 2021, the new API definition takes precedence, but any container types such as endpoint configurations and binary media types are merged with the existing API.
+
+Use the default mode to define top-level RestApi properties in addition to using OpenAPI.
+Generally, it's preferred to use API Gateway's OpenAPI extensions to model these properties.
+
+```ts
+const api = new apigateway.SpecRestApi(this, 'books-api', {
+  apiDefinition: apigateway.ApiDefinition.fromAsset('path-to-file.json'),
+  mode: apigateway.RestApiMode.MERGE
+});
+```


Sorry. I noticed that the description should be below the following statement:

**Note:** When starting off with an OpenAPI definition using `SpecRestApi`, it is not possible to configure some properties that can be configured directly in the OpenAPI specification file. This is to prevent people duplication of these properties and potential confusion.

And it might be good to change the following sentence to be more natural... (Because the description is related to the above statements, or will be in conflict.)

You can control how API Gateway handles resource updates using the `mode` property. Valid values are:

I fixed. Added However, .

go-to-k · 2025-04-22T11:29:09Z

feat(apigateway): add mode propertyto SpecRestApi

😂
propertyto -> property for SpecRestApi

(Or property to SpecRestApiProps is also be good, however I prefer property for SpecRestApi)

tttol · 2025-04-22T11:33:15Z

Umm... I added a space between "property" and "to", but the space is not shown 🤔

Adding two spaces worked fine.

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

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

go-to-k · 2025-04-22T11:41:04Z

Umm... I added a space between "property" and "to", but the space is not shown 🤔

I think it's because you're typing in double-byte (full-width) characters.

So copy and paste this as is. (And it is changed with property for instead of property to)

feat(apigateway): add `mode` property for `SpecRestApi`

shikha372

Thank you @tttol for contributing to this PR, and also @go-to-k for reviewing it thoroughly.

mergify · 2025-04-23T23:17:40Z

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-04-23T23:17:45Z

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.

mergify · 2025-04-23T23:21:36Z

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).

Pull request has been modified.

aws-cdk-automation · 2025-04-24T00:40:35Z

AWS CodeBuild CI Report

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

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

mergify · 2025-04-24T00:41:02Z

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-04-24T00:41:19Z

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.

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

packages/aws-cdk-lib/aws-apigateway/lib/restapi.ts Outdated Show resolved Hide resolved

packages/aws-cdk-lib/aws-apigateway/lib/restapi.ts Outdated Show resolved Hide resolved

packages/aws-cdk-lib/aws-apigateway/lib/restapi.ts Outdated Show resolved Hide resolved

tttol and others added 3 commits April 22, 2025 19:42

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

b210b75

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

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

087fe89

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

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

de68b4f

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

go-to-k approved these changes Apr 22, 2025

View reviewed changes

go-to-k suggested changes Apr 22, 2025

View reviewed changes

tttol changed the title ~~feat(apigateway): support the mode propertyfor how API Gateway resources are updated when using an OpenAPI definition~~ feat(apigateway): add mode propertyto SpecRestApi Apr 22, 2025

fix README

5ae6b9c

tttol changed the title ~~feat(apigateway): add mode propertyto SpecRestApi~~ feat(apigateway): add mode property to SpecRestApi Apr 22, 2025

go-to-k reviewed Apr 22, 2025

View reviewed changes

packages/aws-cdk-lib/aws-apigateway/README.md Outdated Show resolved Hide resolved

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

693dc96

Co-authored-by: Kenta Goto (k.goto) <[email protected]>

tttol changed the title ~~feat(apigateway): add mode property to SpecRestApi~~ feat(apigateway): add mode property for SpecRestApi Apr 22, 2025

go-to-k approved these changes Apr 22, 2025

View reviewed changes

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Apr 22, 2025

shikha372 self-assigned this Apr 22, 2025

shikha372 previously approved these changes Apr 23, 2025

View reviewed changes

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Apr 23, 2025

Merge branch 'main' into add-restapiprops

1a9b9e1

shikha372 approved these changes Apr 24, 2025

View reviewed changes

mergify bot merged commit feadd8c into aws:main Apr 24, 2025
16 of 17 checks passed

github-actions bot locked as resolved and limited conversation to collaborators Apr 24, 2025

tttol deleted the add-restapiprops branch April 27, 2025 07:46


		----

		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 {

feat(apigateway): add mode property for SpecRestApi #34198

feat(apigateway): add mode property for SpecRestApi #34198

Uh oh!

Conversation

tttol commented Apr 18, 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!

tttol commented Apr 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

go-to-k left a comment

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!

tttol Apr 21, 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!

go-to-k Apr 21, 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!

go-to-k commented Apr 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

go-to-k left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

go-to-k left a comment

Choose a reason for hiding this comment

Uh oh!

go-to-k left a comment

Choose a reason for hiding this comment

Uh oh!

go-to-k Apr 22, 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!

go-to-k commented Apr 22, 2025

Uh oh!

tttol commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

go-to-k commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shikha372 left a comment

Choose a reason for hiding this comment

Uh oh!

mergify bot commented Apr 23, 2025

Uh oh!

feat(apigateway): add `mode` property for `SpecRestApi` #34198

feat(apigateway): add `mode` property for `SpecRestApi` #34198

tttol commented Apr 18, 2025 •

edited

Loading

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

go-to-k Apr 22, 2025 •

edited

Loading

tttol commented Apr 22, 2025 •

edited

Loading

go-to-k commented Apr 22, 2025 •

edited

Loading