[apigateway] Construct api resources hierarchically

[mlkirkpatrick]

The idea behind this is similar to #1461, and (less-so) #960. I think it would be beneficial to have an alternate way of defining apigateway resources in CDK that uses a hierarchy. Similar to the swagger approach and SpecRestApi, but as a high level construct that contains resources in the CDK code, with all the benefits of type safety and whatnot.

Use Case

Because an API is structured as a hierarchy of routes, it's easier to construct and read code that is in a similar form. OpenAPI and Swagger accomplish this partially, but they do so by externalizing the resource definition in a declarative language. (Thus losing some of the benefits of using CDK in the first place.)

Creating a construct for this would allow mapping resources dynamically which is not possible using SpecRestApi or similar. A practical example here. (This could be accomplished in the current RestApi implementation using a loop to add resources and methods, but it's not quite as elegant for more complicated definitions that have more variety in integrations and options.)

Could be useful for passing defaults down to child resources as well, although API Gateway already handles this pretty well, it could be useful for path parameters. For example, if you have a route:
/groups/{group}
you would need to define a requestParameter like
'integration.request.path.group': 'method.request.path.group'
then each child resource like /groups/{group}/user also needs to redefine the same parameter even though it can be presumed 99% of the time since the parent needed it. Would need to be able to override or disable inheritance, but I think it would be nice if CDK passed path parameters down to children to reduce repetition.

Proposed Solution

Here is a rough attempt to accomplish a similar development experience to what I am suggesting.
https://gist.github.com/mlkirkpatrick/3befe93726113d19f48a908fb8eebad1

Usage Example:
https://gist.github.com/mlkirkpatrick/758f34e82396db3bde131b3d85387c34

Note that my example is not a proper construct and just appends resources and/or methods to an existing API. I think a proper implementation would probably mean changes to RestApi or a new Api construct altogether, so you can include the whole API definition in one tree.

Other

Most constructs can be fully defined with their constructor props, and optionally have methods that let you change certain properties after initialization. RestApi is one of the few that doesn't give you the option to do so and you basically are required to use the methods after construction for the construct to have any use. I found this strange. It occurred to me that this might be because of underlying limitations with the infrastructure and/or cloudformation, but I also think it should be possible to abstract away this bit in CDK so the user does not need to know about those details and can create their APIs more comfortably.

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

---

This is a 🚀 Feature Request

[nija-at]

@mlkirkpatrick - can you fix some of the broken links above, so I can take a look.

[github-actions]

This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.

[mlkirkpatrick]

Sorry about that. Forgot the repo I linked to was private. I've updated with gists for the examples:
https://gist.github.com/mlkirkpatrick/3befe93726113d19f48a908fb8eebad1
https://gist.github.com/mlkirkpatrick/b0ccad32a47fbe6c6102d1d54e2bf277
https://gist.github.com/mlkirkpatrick/758f34e82396db3bde131b3d85387c34

[nija-at]

This is definitely another way to model REST API resources. Like you mentioned, this would take the same form as the OpenAPI DSL but would be the CDK's own DSL.

I'm going to leave this open here to see how much interest this gathers.

Could be useful for passing defaults down to child resources as well, although API Gateway already handles this pretty well, it could be useful for path parameters. For example, if you have a route:
/groups/{group}
you would need to define a requestParameter like
'integration.request.path.group': 'method.request.path.group'
then each child resource like /groups/{group}/user also needs to redefine the same parameter even though it can be presumed 99% of the time since the parent needed it. Would need to be able to override or disable inheritance, but I think it would be nice if CDK passed path parameters down to children to reduce repetition.

This seems like a useful feature by itself that we should probably incorporate into our current RestApi construct. Why do you say, 99%? When would a user not want this to be automatically applied to propagated to child Resources?

[peterwoodworth]

This is still valid.

@nija-at it looks like this request hasn't gotten much interest, do you think it's worth keeping open? I don't realistically see this getting done anytime soon

[github-actions]

This issue has not received any attention in 1 year. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.