docs(apigateway): update RateLimitedApiKey example code

[akagire]

Issue # (if applicable)

N/A

Reason for this change

RateLimitedApiKey provides associate with provisioned api key and usage plan.
When specify stages, it expects associate with provisioned usage plan and specified stages.

But current behavior did not associate with provisioned usage plan and specified stages but also gives stage like current documents example code.

Considering the context in which RateLimitedApiKey is implemented, it makes sense to associate with provisioned usage plan and specified stages.

Description of changes

Changed sample code to use apiStages instead of stages as get expected behavior.

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]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 89a0dbc
• Result: SUCCEEDED
• Build Logs (available for 30 days)

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

[mazyu36]

It seems that the RateLimitApiKey has a stages property.
Can you tell me more about the meaning of 'not available'?

[akagire]

@mazyu36 When I used the stages, I observed that while the api key was associated with the provisioned Usage Plan. But the Stage was not. This is what I meant by "not available". ( I realizing this expression was not good...)

If we were to follow the sample code using stages, it would be necessary to call plan.addApiStage. That means would require declaring the UsagePlan explicitly.
In such a case, since we would be setting the rate limit in declare UsagePlan, the necessity of RateLimitedApiKey becomes unclear.

Therefore, I read #6509 to understand the context behind the implementation of RateLimitedApiKey.
I gathered that it was implemented to declare rate limit related configure and associated with usage plan and stage, not only declaring api key.
if current behavior and my understanding is correct, I think sample code is suitable for using apiStages instead of stages

Could you please advice me when my understand is wrong?

[mazyu36]

@akagire
Thank you for the explanation.
I see that apiStages are indeed linked to the UsagePlan as you described.
https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-apigateway/lib/api-key.ts#L261

Since this modification aligns the code example with a more appropriate use case, I think it's fine.
Let's see what the maintainers think about it.

Could you please update the issue description?
This is because the stages property itself is not actually unavailable.

[kaizencc]

@akagire thanks for taking on this doc update! it seems confusing to me that apiStages and stages are both available on the construct but are applied in different areas. if that's not a bug, can we also add in the README a more clear distinction for how those properties differ?

[akagire]

@mazyu36 I updated.

@kaizencc Honestly, I cannot describe those distinction yet but I'll try to and investigate. The possibility of a bug has not been ruled out. If so, I'll post new issue.

[kaizencc]

this still seems like an open thread that should be closed before this PR is merged

[mazyu36]

Thank you for your contribution. I've included one question.