aws / aws/aws-cdk

aws-apigateway: Automatically adding path parameters for proxy resources

Open
#28,545 5 comments 22 reactions 0 assignees View on GitHub
@aws-cdk/aws-apigateway effort/medium feature-request p1
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

When trying to create proxy resource of `/api/{proxy+}` in REST API like this

```typescript
const api = new apigateway.RestApi(this, 'MyApi', {});
api.root.addResource('api').addProxy({
anyMethod: true,
defaultIntegration: new apigateway.HttpIntegration(
`http://${prodDomainName}/api/{proxy}`,
{
proxy: true,
httpMethod: 'ANY',
options: {
vpcLink,
connectionType: ConnectionType.VPC_LINK,
}
},
),
});
```
The proxy resource it creates is missing path parameter for `proxy`, resulting it always sending request to integration backend on the path `/api/`, which isn't what we intuitively want for the proxy resource.

What it requires is two additional configs, one in the method, and one in the integration
```typescript
api.root.addResource('api').addProxy({
anyMethod: true,
defaultIntegration: new apigateway.HttpIntegration(
`http://${prodDomainName}/api/{proxy}`,
{
proxy: true,
httpMethod: 'ANY',
options: {
vpcLink,
connectionType: ConnectionType.VPC_LINK,
requestParameters: { 'integration.request.path.proxy': 'method.request.path.proxy' },
}
},
),
defaultMethodOptions: {
requestParameters: { 'method.request.path.proxy': true },
},
});
```
It would be nice if CDK can automatically configure `integration.request.path.proxy` and `method.request.path.proxy` for proxy resources, so we don't have to explicitly configure them, similar to the UX from AWS console, when adding a proxy resource manually through the UI, these path params are automatically set.

### Use Case

To make CDK work out of the box with sensible defaults when creating proxy resources, without requiring deep knowledge of nuances of API Gateway.

It took me a long time searching on the web, and still couldn't figure out the part where I originally missed
```
defaultMethodOptions: {
requestParameters: { 'method.request.path.proxy': true },
},
```
These are some relevant docs I could find during my initial search:
- https://docs.aws.amazon.com/apigateway/latest/developerguide/setup-http-integrations.html#api-gateway-set-up-http-proxy-integration-on-proxy-resource , it only mentioned `'integration.request.path.proxy': 'method.request.path.proxy'` but not `'method.request.path.proxy': true`;
- https://stackoverflow.com/questions/70717030/path-parameters-ignored-by-aws-api-gateway-using-proxy , the accepted answer didn't mention `'method.request.path.proxy': true` neither; while the other answer did show `method.request.path.proxy: true # enable proxy`, it's very easy to miss and hard to correlate with corresponding CDK code.

With the above docs, I only added `requestParameters: { 'integration.request.path.proxy': 'method.request.path.proxy' },` to my integration, and got error:
```
Invalid mapping expression specified: Validation Result: warnings : [], errors : [Invalid mapping expression parameter specified: method.request.path.proxy]
```
Which is arguably confusing and unhelpful for someone doesn't already familiar with API Gateway nuances.

This remained a mystery for me until I contacted AWS support that the support technician pointed out my missing part and where the related official doc is located
- https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#apigw-Type-Integration-requestParameters

Which is arguably very difficult to find and correlate it with my problem when I'm not already familiar with various nuances of API Gateway, as I was searching for solutions specifically about how to make the proxy working.

### Proposed Solution

maybe add a parameter `proxyParamName` to `ProxyResourceOptions`, so we can call `addProxy()` like
```typescript
addProxy({
anyMethod: true,
proxyParamName: 'myProxyParam',
....
```
Then it will automatically set `'method.request.path.myProxyParam': true` and `'integration.request.path.myProxyParam': 'method.request.path.myProxyParam'`

### Other Information

_No response_

### Acknowledgements

- [ ] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### CDK version used

2.115.0

### Environment details (OS name and version, etc.)

N/A

Contributor guide

Open the contributing guide

Research direction

Start by tracing the addProxy() entry point and ProxyResourceOptions, then inspect how proxy methods and integrations currently receive requestParameters. Confirm the desired behavior for the proxy parameter name and validate the generated method and integration mappings in the existing API Gateway tests; done means proxy resources forward the path parameter without requiring manual configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
api, cloud
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.