feat(apigatewayv2-integrations): http api - support for request parameter mapping

packages/@aws-cdk/aws-apigatewayv2-integrations/README.md

@@ -21,6 +21,7 @@
   - [Lambda Integration](#lambda)
   - [HTTP Proxy Integration](#http-proxy)
   - [Private Integration](#private-integration)
+  - [Request Parameters](#request-parameters)
 - [WebSocket APIs](#websocket-apis)
   - [Lambda WebSocket Integration](#lambda-websocket-integration)
 
@@ -149,6 +150,40 @@ const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
 });
 ```
 
+### Request Parameters
+
+Request parameter mapping allows API requests from clients to be modified before they reach backend integrations.
+Parameter mapping can be used to specify modifications to request parameters. See [Transforming API requests and
+responses](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html).
+
+The following example creates a new header - `header2` - as a copy of `header1` and removes `header1`.
+
+```ts
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    // ...
+    requestParameters: new ParameterMapping()
+      .appendHeader('header2', MappingValue.header('header1'))
+      .removeHeader('header1');
+    }),
+  }),
+});
+```
+
+To add mapping keys and values not yet supported by the CDK, use the `custom()` method:
+
+```ts
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    listener,
+    requestParameters: new ParameterMapping()
+      .custom('myKey', 'myValue'),
+    }),
+  }),
+});
+```
+
+
 ## WebSocket APIs
 
 WebSocket integrations connect a route to backend resources. The following integrations are supported in the CDK.

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/alb.ts

@@ -44,6 +44,7 @@ export class HttpAlbIntegration extends HttpPrivateIntegration {
       connectionId: vpcLink.vpcLinkId,
       uri: this.props.listener.listenerArn,
       secureServerName: this.props.secureServerName,
+      parameterMapping: this.props.parameterMapping,
     };
   }
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/base-types.ts

@@ -1,4 +1,4 @@
-import { HttpMethod, IVpcLink } from '@aws-cdk/aws-apigatewayv2';
+import { HttpMethod, IVpcLink, ParameterMapping } from '@aws-cdk/aws-apigatewayv2';
 
 /**
  * Base options for private integration
@@ -24,4 +24,11 @@ export interface HttpPrivateIntegrationOptions {
   */
 
   readonly secureServerName?: string;
+
+  /**
+  * Specifies how to transform HTTP requests before sending them to the backend
+  * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html
+  * @default undefined requests are sent to the backend unmodified
+  */
+  readonly parameterMapping?: ParameterMapping;
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/http-proxy.ts

@@ -4,6 +4,7 @@ import {
   HttpRouteIntegrationConfig,
   HttpMethod,
   IHttpRouteIntegration,
+  ParameterMapping,
   PayloadFormatVersion,
 } from '@aws-cdk/aws-apigatewayv2';
 
@@ -21,6 +22,13 @@ export interface HttpProxyIntegrationProps {
    * @default HttpMethod.ANY
    */
   readonly method?: HttpMethod;
+
+  /**
+   * Specifies how to transform HTTP requests before sending them to the backend
+   * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html
+   * @default undefined requests are sent to the backend unmodified
+   */
+  readonly parameterMapping?: ParameterMapping;
 }
 
 /**
@@ -36,6 +44,7 @@ export class HttpProxyIntegration implements IHttpRouteIntegration {
       payloadFormatVersion: PayloadFormatVersion.VERSION_1_0, // 1.0 is required and is the only supported format
       type: HttpIntegrationType.HTTP_PROXY,
       uri: this.props.url,
+      parameterMapping: this.props.parameterMapping,
     };
   }
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/lambda.ts

@@ -4,6 +4,7 @@ import {
   HttpRouteIntegrationConfig,
   IHttpRouteIntegration,
   PayloadFormatVersion,
+  ParameterMapping,
 } from '@aws-cdk/aws-apigatewayv2';
 import { ServicePrincipal } from '@aws-cdk/aws-iam';
 import { IFunction } from '@aws-cdk/aws-lambda';
@@ -24,6 +25,13 @@ export interface LambdaProxyIntegrationProps {
    * @default PayloadFormatVersion.VERSION_2_0
    */
   readonly payloadFormatVersion?: PayloadFormatVersion;
+
+  /**
+   * Specifies how to transform HTTP requests before sending them to the backend
+   * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-parameter-mapping.html
+   * @default undefined requests are sent to the backend unmodified
+   */
+  readonly parameterMapping?: ParameterMapping;
 }
 
 /**
@@ -50,6 +58,7 @@ export class LambdaProxyIntegration implements IHttpRouteIntegration {
       type: HttpIntegrationType.LAMBDA_PROXY,
       uri: this.props.handler.functionArn,
       payloadFormatVersion: this.props.payloadFormatVersion ?? PayloadFormatVersion.VERSION_2_0,
+      parameterMapping: this.props.parameterMapping,
     };
   }
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/nlb.ts

@@ -44,6 +44,7 @@ export class HttpNlbIntegration extends HttpPrivateIntegration {
       connectionId: vpcLink.vpcLinkId,
       uri: this.props.listener.listenerArn,
       secureServerName: this.props.secureServerName,
+      parameterMapping: this.props.parameterMapping,
     };
   }
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/lib/http/service-discovery.ts

@@ -34,6 +34,7 @@ export class HttpServiceDiscoveryIntegration extends HttpPrivateIntegration {
       connectionId: this.props.vpcLink.vpcLinkId,
       uri: this.props.service.serviceArn,
       secureServerName: this.props.secureServerName,
+      parameterMapping: this.props.parameterMapping,
     };
   }
 }

packages/@aws-cdk/aws-apigatewayv2-integrations/test/http/alb.test.ts

@@ -1,5 +1,5 @@
 import { Template } from '@aws-cdk/assertions';
-import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, VpcLink } from '@aws-cdk/aws-apigatewayv2';
+import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, VpcLink, ParameterMapping, MappingValue } from '@aws-cdk/aws-apigatewayv2';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as elbv2 from '@aws-cdk/aws-elasticloadbalancingv2';
 import { Stack } from '@aws-cdk/core';
@@ -143,4 +143,34 @@ describe('HttpAlbIntegration', () => {
       },
     });
   });
+
+  test('parameterMapping option is correctly recognized', () => {
+    // GIVEN
+    const stack = new Stack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const lb = new elbv2.ApplicationLoadBalancer(stack, 'lb', { vpc });
+    const listener = lb.addListener('listener', { port: 80 });
+    listener.addTargets('target', { port: 80 });
+
+    // WHEN
+    const api = new HttpApi(stack, 'HttpApi');
+    new HttpRoute(stack, 'HttpProxyPrivateRoute', {
+      httpApi: api,
+      integration: new HttpAlbIntegration({
+        listener,
+        parameterMapping: new ParameterMapping()
+          .appendHeader('header2', MappingValue.requestHeader('header1'))
+          .removeHeader('header1'),
+      }),
+      routeKey: HttpRouteKey.with('/pets'),
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Integration', {
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+  });
 });

packages/@aws-cdk/aws-apigatewayv2-integrations/test/http/http-proxy.test.ts

@@ -1,5 +1,5 @@
 import { Template } from '@aws-cdk/assertions';
-import { HttpApi, HttpIntegration, HttpIntegrationType, HttpMethod, HttpRoute, HttpRouteKey, PayloadFormatVersion } from '@aws-cdk/aws-apigatewayv2';
+import { HttpApi, HttpIntegration, HttpIntegrationType, HttpMethod, HttpRoute, HttpRouteKey, MappingValue, ParameterMapping, PayloadFormatVersion } from '@aws-cdk/aws-apigatewayv2';
 import { Stack } from '@aws-cdk/core';
 import { HttpProxyIntegration } from '../../lib';
 
@@ -71,4 +71,26 @@ describe('HttpProxyIntegration', () => {
       IntegrationUri: 'some-target-url',
     });
   });
+
+  test('parameterMapping is correctly recognized', () => {
+    const stack = new Stack();
+    const api = new HttpApi(stack, 'HttpApi');
+    new HttpIntegration(stack, 'HttpInteg', {
+      httpApi: api,
+      integrationType: HttpIntegrationType.HTTP_PROXY,
+      integrationUri: 'some-target-url',
+      parameterMapping: new ParameterMapping()
+        .appendHeader('header2', MappingValue.requestHeader('header1'))
+        .removeHeader('header1'),
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Integration', {
+      IntegrationType: 'HTTP_PROXY',
+      IntegrationUri: 'some-target-url',
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+  });
 });

packages/@aws-cdk/aws-apigatewayv2-integrations/test/http/lambda.test.ts

@@ -1,5 +1,5 @@
 import { Template } from '@aws-cdk/assertions';
-import { HttpApi, HttpRoute, HttpRouteKey, PayloadFormatVersion } from '@aws-cdk/aws-apigatewayv2';
+import { HttpApi, HttpRoute, HttpRouteKey, MappingValue, ParameterMapping, PayloadFormatVersion } from '@aws-cdk/aws-apigatewayv2';
 import { Code, Function, Runtime } from '@aws-cdk/aws-lambda';
 import { App, Stack } from '@aws-cdk/core';
 import { LambdaProxyIntegration } from '../../lib';
@@ -41,6 +41,28 @@ describe('LambdaProxyIntegration', () => {
     });
   });
 
+  test('parameterMapping selection', () => {
+    const stack = new Stack();
+    const api = new HttpApi(stack, 'HttpApi');
+    new HttpRoute(stack, 'LambdaProxyRoute', {
+      httpApi: api,
+      integration: new LambdaProxyIntegration({
+        handler: fooFunction(stack, 'Fn'),
+        parameterMapping: new ParameterMapping()
+          .appendHeader('header2', MappingValue.requestHeader('header1'))
+          .removeHeader('header1'),
+      }),
+      routeKey: HttpRouteKey.with('/pets'),
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Integration', {
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+  });
+
   test('no dependency cycles', () => {
     const app = new App();
     const lambdaStack = new Stack(app, 'lambdaStack');

packages/@aws-cdk/aws-apigatewayv2-integrations/test/http/nlb.test.ts

@@ -1,5 +1,5 @@
 import { Template } from '@aws-cdk/assertions';
-import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, VpcLink } from '@aws-cdk/aws-apigatewayv2';
+import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, MappingValue, ParameterMapping, VpcLink } from '@aws-cdk/aws-apigatewayv2';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as elbv2 from '@aws-cdk/aws-elasticloadbalancingv2';
 import { Stack } from '@aws-cdk/core';
@@ -140,4 +140,34 @@ describe('HttpNlbIntegration', () => {
       },
     });
   });
+
+  test('paramaterMapping option is correctly recognized', () => {
+    // GIVEN
+    const stack = new Stack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const lb = new elbv2.NetworkLoadBalancer(stack, 'lb', { vpc });
+    const listener = lb.addListener('listener', { port: 80 });
+    listener.addTargets('target', { port: 80 });
+
+    // WHEN
+    const api = new HttpApi(stack, 'HttpApi');
+    new HttpRoute(stack, 'HttpProxyPrivateRoute', {
+      httpApi: api,
+      integration: new HttpNlbIntegration({
+        listener,
+        parameterMapping: new ParameterMapping()
+          .appendHeader('header2', MappingValue.requestHeader('header1'))
+          .removeHeader('header1'),
+      }),
+      routeKey: HttpRouteKey.with('/pets'),
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Integration', {
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+  });
 });

packages/@aws-cdk/aws-apigatewayv2-integrations/test/http/service-discovery.test.ts

@@ -1,5 +1,5 @@
 import { Template } from '@aws-cdk/assertions';
-import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, VpcLink } from '@aws-cdk/aws-apigatewayv2';
+import { HttpApi, HttpMethod, HttpRoute, HttpRouteKey, MappingValue, ParameterMapping, VpcLink } from '@aws-cdk/aws-apigatewayv2';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as servicediscovery from '@aws-cdk/aws-servicediscovery';
 import { Stack } from '@aws-cdk/core';
@@ -125,4 +125,38 @@ describe('HttpServiceDiscoveryIntegration', () => {
       },
     });
   });
+
+  test('parameterMapping option is correctly recognized', () => {
+    // GIVEN
+    const stack = new Stack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const vpcLink = new VpcLink(stack, 'VpcLink', { vpc });
+    const namespace = new servicediscovery.PrivateDnsNamespace(stack, 'Namespace', {
+      name: 'foobar.com',
+      vpc,
+    });
+    const service = namespace.createService('Service');
+
+    // WHEN
+    const api = new HttpApi(stack, 'HttpApi');
+    new HttpRoute(stack, 'HttpProxyPrivateRoute', {
+      httpApi: api,
+      integration: new HttpServiceDiscoveryIntegration({
+        vpcLink,
+        service,
+        parameterMapping: new ParameterMapping()
+          .appendHeader('header2', MappingValue.requestHeader('header1'))
+          .removeHeader('header1'),
+      }),
+      routeKey: HttpRouteKey.with('/pets'),
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Integration', {
+      RequestParameters: {
+        'append:header.header2': '$request.header.header1',
+        'remove:header.header1': '',
+      },
+    });
+  });
 });

packages/@aws-cdk/aws-apigatewayv2/lib/http/api.ts

@@ -305,6 +305,7 @@ abstract class HttpApiBase extends ApiBase implements IHttpApi { // note that th
       connectionType: config.connectionType,
       payloadFormatVersion: config.payloadFormatVersion,
       secureServerName: config.secureServerName,
+      parameterMapping: config.parameterMapping,
     });
     this._integrationCache.saveIntegration(scope, config, integration);