aws-apigateway: Automatically adding path parameters for proxy resources

[dachaoli-finfare]

Describe the feature

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

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

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

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

[pahud]

Makes sense to me though we probably need more discussion from the community.

Thank you for your feature request.

[villapx-path]

Wish I had found this issue sooner -- I just lost about a day and a half of work due to these omissions from the documentation. Adding the request_parameters arguments to both the aws_api_gateway_integration and aws_api_gateway_method terraform resources was the final missing piece to get my proxy integration working. Thank you @dachaoli-finfare!