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,52 @@ const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
 });
 ```
 
+### Request Parameters
+
+Request parameter mapping allows API requests from clients to be modified before they reach backend integrations.
+To use parameter mapping, you specify API request parameters to modify, and specify how to modify the parameters. 
+
+Request parameter mapping is supported through a set of helper methods.
+The following example renames a request header from header1 to header2 by generating mappings
+`append:header.header2: $request.header.header1` and `remove:header.header1: ''`:
+
+```ts
+const vpc = new ec2.Vpc(stack, 'VPC');
+const lb = new elbv2.ALB(stack, 'lb', { vpc });
+const listener = lb.addListener('listener', { port: 80 });
+listener.addTargets('target', {
+  port: 80,
+});
+
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    listener,
+    requestParameters: new ParameterMapping()
+      .appendHeader('header2', MappingValue.header('header1'))
+      .removeHeader('header1');
+    }),
+  }),
+});
+```
+
+
+
+To use values which does not yet have any helper functions, you can use the custom methods:
+
+```ts
+const httpEndpoint = new HttpApi(stack, 'HttpProxyPrivateApi', {
+  defaultIntegration: new HttpAlbIntegration({
+    listener,
+    requestParameters: new RequestParameters()
+      .addParameter({
+        mappingKey: MappingKey.custom('new.header'),
+        mappingValue: MappingValue.custom('new.value'),
+    }),
+  }),
+});
+```
+
+
 ## WebSocket APIs
 
 WebSocket integrations connect a route to backend resources. The following integrations are supported in the CDK.

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);
 

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

@@ -74,6 +74,60 @@ export class PayloadFormatVersion {
   }
 }
 
+export interface IMappingKey {
+  key: string;
+};
+
+export interface IMappingValue {
+  value: string;
+};
+
+export class MappingKey implements IMappingKey {
+  public static custom(mappingKey: string) {return new MappingKey(mappingKey); }
+  protected constructor(public readonly key: string) {}
+}
+
+export class HttpMappingKey extends MappingKey {
+  public static appendHeader(name: string) { return new MappingKey(`append:header.${name}`); }
+  public static overwriteHeader(name: string) { return new MappingKey(`overwrite:header.${name}`); }
+  public static removeHeader(name: string) { return new MappingKey(`remove:header.${name}`); }
+  public static appendQueryString(name: string) {return new MappingKey(`append:querystring.${name}`); }
+  public static overwriteQueryString(name: string) { return new MappingKey(`overwrite:querystring.${name}`); }
+  public static removeQueryString(name: string) { return new MappingKey(`remove:querystring.${name}`); }
+  public static overwritePath() { return new MappingKey('overwrite:path'); }
+  protected constructor(public readonly k: string) {
+    super(k);
+  }
+}
+
+export class MappingValue implements IMappingValue {
+  public static readonly NONE = new MappingValue('');
+  public static requestHeader(name: string) { return new MappingValue(`$request.header.${name}`); }
+  public static requestQueryString(name: string) { return new MappingValue(`$request.querystring.${name}`); }
+  public static requestBody(name: string) { return new MappingValue(`$request.body.${name}`); }
+  public static requestPathFull() {return new MappingValue('$request.path'); }
+  public static requestPath(name: string) { return new MappingValue(`$request.path.${name}`); }
+  public static contextVariable(variableName: string) { return new MappingValue(`$context.${variableName}`); }
+  public static stageVariablesVariable(variableName: string) { return new MappingValue(`$stageVariables.${variableName}`); }
+  public static custom(value: string) {return new MappingValue(value); }
+  protected constructor(public readonly value: string) {}
+}
+
+export interface ParameterMappingProps {
+  readonly key: IMappingKey,
+  readonly value: IMappingValue,
+};
+
+export class ParameterMapping {
+  public readonly mappings: {[key: string]: string}
+  constructor(params: ParameterMappingProps[]) {
+    this.mappings = {};
+    params.forEach(param => {
+      this.mappings[param.key.key] = param.value.value;
+    });
+  }
+}
+
 /**
  * The integration properties
  */
@@ -128,6 +182,8 @@ export interface HttpIntegrationProps {
    * @default undefined private integration traffic will use HTTP protocol
    */
   readonly secureServerName?: string;
+
+  readonly parameterMapping?: ParameterMapping;
 }
 
 /**
@@ -149,6 +205,7 @@ export class HttpIntegration extends Resource implements IHttpIntegration {
       connectionId: props.connectionId,
       connectionType: props.connectionType,
       payloadFormatVersion: props.payloadFormatVersion?.version,
+      requestParameters: props.parameterMapping?.mappings,
     });
 
     if (props.secureServerName) {
@@ -237,4 +294,6 @@ export interface HttpRouteIntegrationConfig {
    * @default undefined private integration traffic will use HTTP protocol
    */
   readonly secureServerName?: string;
+
+  readonly parameterMapping?: ParameterMapping;
 }

packages/@aws-cdk/aws-apigatewayv2/test/http/route.test.ts

@@ -1,8 +1,9 @@
 import '@aws-cdk/assert-internal/jest';
 import { Stack, App } from '@aws-cdk/core';
 import {
-  HttpApi, HttpAuthorizer, HttpAuthorizerType, HttpConnectionType, HttpIntegrationType, HttpMethod, HttpRoute, HttpRouteAuthorizerBindOptions,
-  HttpRouteAuthorizerConfig, HttpRouteIntegrationConfig, HttpRouteKey, IHttpRouteAuthorizer, IHttpRouteIntegration, PayloadFormatVersion,
+  HttpApi, HttpAuthorizer, HttpAuthorizerType, HttpConnectionType, HttpIntegrationType, HttpMappingKey, HttpMethod, HttpRoute,
+  HttpRouteAuthorizerBindOptions, HttpRouteAuthorizerConfig, HttpRouteIntegrationConfig, HttpRouteKey, IHttpRouteAuthorizer, IHttpRouteIntegration,
+  MappingValue, ParameterMapping, PayloadFormatVersion,
 } from '../../lib';
 
 describe('HttpRoute', () => {
@@ -174,6 +175,18 @@ describe('HttpRoute', () => {
           connectionType: HttpConnectionType.VPC_LINK,
           uri: 'some-target-arn',
           secureServerName: 'some-server-name',
+          parameterMapping: new ParameterMapping(
+            [
+              {
+                key: HttpMappingKey.appendHeader('header2'),
+                value: MappingValue.requestHeader('header1'),
+              },
+              {
+                key: HttpMappingKey.removeHeader('header1'),
+                value: MappingValue.NONE,
+              },
+            ],
+          ),
         };
       }
     }