How do I resolve "Invalid mapping expression specified" errors from API Gateway?

Short description

When the proxy path parameter {proxy+} doesn't have a defined URL path parameter mapping, API Gateway returns an "Invalid mapping expression specified" error message.

To resolve this issue, complete the steps for the tool that you used to create the API.

Resolution

CloudFormation template

Define the RequestParameters property of the AWS::ApiGateway::Method section.

Complete the following steps:

1. Update the CloudFormation template so that the RequestParameters value is set to true.

   Example template:

   ....
   .
     ProxyMethod:
       Type: 'AWS::ApiGateway::Method'
       Properties:
         .
         .
         RequestParameters:
          
           method.request.path.proxy: true
          
         Integration:
           RequestParameters:
             integration.request.path.proxy: 'method.request.path.proxy'
          
           IntegrationHttpMethod: ANY
           .
           .
   ...

2. To update your API, use the CloudFormation template to update the CloudFormation stack.

Note: For more information about how to update API Gateway resources, see Amazon API Gateway resource type reference.

OpenAPI definition

Define the parameters section in the x-amazon-apigateway-any-method object.

Complete the following steps:

1. Update your API definition so that the parameters under the x-amazon-apigateway-any-method section have the following values:

         "x-amazon-apigateway-any-method": {                "parameters": [
             {
               "name": "proxy",
               "in": "path",
               "required": true,
               "type": "string"
             }
           ]
   
   ....
   
   ....
   
   }

2. Import your updated API definition file into API Gateway to update your API.

Note: For more information, see Describing parameters on the Swagger website.

AWS CLI command

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

When you run the put-integration command to set up integration, add the --request-parameters.

1. Run the update-method command to update the Method Request configuration of the HTTP method:

   aws apigateway update-method \
       --rest-api-id <your-api-id> \
       --resource-id <your-resource-id> \
       --http-method <your-http-method> \
       --patch-operations op="add",path="/requestParameters/method.request.path.proxy",value="true"

2. Run the put-integration command to update the Integration Request configuration of the HTTP method that has --request-parameters. The example parameter is named proxy and has a value of method.request.path.proxy. The put-integration command sets up an HTTP_PROXY integration with a VPC Link:

   aws apigateway put-integration \
       --rest-api-id <your-api-id>\
       --resource-id <your-resource-id> \
       --http-method <your-http-method> \
       --type HTTP_PROXY \
       --integration-http-method <your-integration-http-method> \
       --uri "<your-integration-endpoint-uri>" \
       --connection-type VPC_LINK \
       --connection-id <your-vpclink-connection-id> \
       --request-parameters "integration.request.path.proxy=method.request.path.proxy"

   Note: Replace all example values with your values.

Test the setup

Complete the following steps:

1. Open the API Gateway console, and then choose the name of your API.
2. Add URL path parameters.
   Note: If your proxy path parameter includes a correctly defined URL path parameter mapping, then no error appears.

Related information

x-amazon-apigateway-integration.requestParameters object

Set up a proxy integration with a proxy resource

Setting up data transformations for REST APIs