aws-apigateway: Documentation lacks information about stack separation for RestApi and Resources

[engineer-taro]

Describe the issue

Overview

In this documentation, I would like to note that when separating the stacks for RestApi and Resource, Deployment is not automatically created, and to avoid this issue, it is necessary to use Deployment.addToLogicalId().

Details

When a Resource is added to an IRestApi imported via RestApi.fromRestApiAttribute or RestApi.fromRestApiId, Deployment is not created, so the latest resource state is not associated with the API Gateway stage, which is a known issue.
This has been discussed in several issues, including the following:

• (aws-apigateway): RestApi imported with method fromRestApiAttributes not updating current deployment in stage #13526
• AWS APIgateway: fromRestApiAttributes does not bring all the RestAPI configuration #29079

We understand that it is not easy to automatically create Deployment, and there may be differing opinions on whether it should be fixed.
However, since there is no mention of this issue in the documentation, we feel that many developers who are separating stacks related to API Gateway may unintentionally create an environment where Deployment is not created.
Due to this issue, developers need to manually deploy to API Gateway after running cdk deploy.

While it is possible to share a workaround implementation, it is difficult to implement an automatic Deployment creation that detects changes in Resource without increasing complexity in the current configuration.

Therefore, we would like to propose adding a note to the documentation first.

Links

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway-readme.html#breaking-up-methods-and-resources-across-stacks

[tim-finnigan]

Thanks for creating the issue/PR. There is a note in https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Deployment.html that says:

Normally, you don't need to define deployments manually. The RestApi construct manages a Deployment resource that represents the latest model. It can be accessed through restApi.latestDeployment (unless deploy: false is set when defining the RestApi).

If you manually define this resource, you will need to know that since deployments are immutable, as long as the resource's logical ID doesn't change, the deployment will represent the snapshot in time in which the resource was created. This means that if you modify the RestApi model (i.e. add methods or resources), these changes will not be reflected unless a new deployment resource is created.

To achieve this behavior, the method addToLogicalId(data) can be used to augment the logical ID generated for the deployment resource such that it will include arbitrary data. This is done automatically for the restApi.latestDeployment deployment.

Also here is a link to another workaround in that latter issue you referenced.

Maybe further clarification is needed in the docs but I'm not sure about just linking #13526 in your PR.

[engineer-taro]

@tim-finnigan
Thank you, tim-finnigan.

Also here is a link to another workaround in that latter issue you referenced.

The code provided in the other workaround you suggested does not solve the problem I presented.
#29079 (comment)

With that code as well, no new Deployment is created on the 2nd and subsequent cdk deploy, so the same issue of the latest resources not being reflected would still occur.

Maybe further clarification is needed in the docs but I'm not sure about just linking #13526 in your PR.

Thank you. I also don't think just linking the issue being discussed is the optimal solution.
I would appreciate if you could provide your opinion on whether we should add more details to other issues or the documentation.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[aws-cdk-automation]

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.