AWS apigateway documentation change
Summary
Restructured documentation from example-based format to reference material, adding detailed mapping syntax tables and OpenAPI examples while removing step-by-step console instructions
Security assessment
Changes focus on general data mapping syntax and reference material without mentioning security vulnerabilities, protections, or specific security features. While mapping configurations can impact security, there's no explicit discussion of security implications in the diff.
Diff
diff --git a/apigateway/latest/developerguide/request-response-data-mappings.md b/Users/docs/2025-03-10_15-36-52/apigateway/latest/developerguide/request-response-data-mappings.md index baa5ddf66..b6c9cbb09 100644 --- a/apigateway/latest/developerguide/request-response-data-mappings.md +++ b/apigateway/latest/developerguide/request-response-data-mappings.md @@ -5 +5 @@ -Example 1: Map a method request parameter to an integration request parameterExample 2: Map multiple method request parameters to different integration request parametersExample 3: Map fields from the JSON request body to integration request parametersExample 4: Map the integration response to the method response +Map method request data to integration request parametersMap integration response data to method response headersMap request and response payloads between method and integration @@ -7 +7 @@ Example 1: Map a method request parameter to an integration request parameterExa -# Parameter mapping examples for REST APIs in API Gateway +# Amazon API Gateway API request and response data mapping reference @@ -9 +9 @@ Example 1: Map a method request parameter to an integration request parameterExa -The following examples show how to create parameter mapping expressions using the API Gateway console, OpenAPI, and AWS CloudFormation templates. For an example of how to use parameter mapping to create the required CORS headers, see [CORS for REST APIs in API Gateway](./how-to-cors.html). +This section explains how to set up data mappings from an API's method request data, including other data stored in [context](./api-gateway-mapping-template-reference.html#context-variable-reference), [stage](./api-gateway-mapping-template-reference.html#stagevariables-template-reference), or [util](./api-gateway-mapping-template-reference.html#util-template-reference) variables, to the corresponding integration request parameters and from an integration response data, including the other data, to the method response parameters. The method request data includes request parameters (path, query string, headers) and the body. The integration response data includes response parameters (headers) and the body. For more information about using the stage variables, see [API Gateway stage variables reference for REST APIs in API Gateway](./aws-api-gateway-stage-variables-reference.html). @@ -11 +11 @@ The following examples show how to create parameter mapping expressions using th -## Example 1: Map a method request parameter to an integration request parameter +###### Topics @@ -13 +13 @@ The following examples show how to create parameter mapping expressions using th -The following example maps the method request header parameter `puppies` to the integration request header parameter `DogsAge0`. + * Map method request data to integration request parameters @@ -15 +15 @@ The following example maps the method request header parameter `puppies` to the -AWS Management Console + * Map integration response data to method response headers @@ -16,0 +17 @@ AWS Management Console + * Map request and response payloads between method and integration @@ -18 +19 @@ AWS Management Console -###### To map the method request parameter + * [Integration passthrough behaviors](./integration-passthrough-behaviors.html) @@ -20 +20,0 @@ AWS Management Console - 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). @@ -22 +21,0 @@ AWS Management Console - 2. Choose a REST API. @@ -24 +22,0 @@ AWS Management Console - 3. Choose a method. @@ -26 +24 @@ AWS Management Console -Your method must have a non-proxy integration. +## Map method request data to integration request parameters @@ -28 +26 @@ Your method must have a non-proxy integration. - 4. For **Method request settings** , choose **Edit**. +Integration request parameters, in the form of path variables, query strings or headers, can be mapped from any defined method request parameters and the payload. @@ -30 +28 @@ Your method must have a non-proxy integration. - 5. Choose **HTTP request headers**. +In the following table, ``PARAM_NAME`` is the name of a method request parameter of the given parameter type. It must match the regular expression `'^[a-zA-Z0-9._$-]+$]'`. It must have been defined before it can be referenced. ``JSONPath_EXPRESSION`` is a JSONPath expression for a JSON field of the body of a request or response. @@ -32 +30 @@ Your method must have a non-proxy integration. - 6. Choose **Add header**. +###### Note @@ -34 +32 @@ Your method must have a non-proxy integration. - 7. For **Name** , enter `puppies`. +The `"$"` prefix is omitted in this syntax. @@ -36 +34,12 @@ Your method must have a non-proxy integration. - 8. Choose **Save**. +**Mapped data source** | **Mapping expression** +---|--- +Method request path | `method.request.path.`PARAM_NAME`` +Method request query string | `method.request.querystring.`PARAM_NAME`` +Multi-value method request query string | `method.request.multivaluequerystring.`PARAM_NAME`` +Method request header | `method.request.header.`PARAM_NAME`` +Multi-value method request header | `method.request.multivalueheader.`PARAM_NAME`` +Method request body | `method.request.body` +Method request body (JsonPath) | `method.request.body.`JSONPath_EXPRESSION``. +Stage variables | `stageVariables.`VARIABLE_NAME`` +Context variables | `context.`VARIABLE_NAME`` that must be one of the [supported context variables](./api-gateway-mapping-template-reference.html#context-variable-reference). +Static value | ``'STATIC_VALUE'``. The `STATIC_VALUE` is a string literal and must be enclosed within a pair of single quotes. @@ -38 +47 @@ Your method must have a non-proxy integration. - 9. Choose the **Integration request** tab, and then for **Integration request settings** , choose **Edit**. +###### Example Mappings from method request parameter in OpenAPI @@ -40 +49 @@ Your method must have a non-proxy integration. -The AWS Management Console automatically adds a parameter mapping from `method.request.header.puppies ` to `puppies` for you, but you need to change the **Name** to match the request header parameter that is expected by your integration endpoint. +The following example shows an OpenAPI snippet that maps: @@ -42 +51 @@ The AWS Management Console automatically adds a parameter mapping from `method.r - 10. For **Name** , enter `DogsAge0`. + * the method request's header, named `methodRequestHeaderParam`, into the integration request path parameter, named `integrationPathParam` @@ -44 +53 @@ The AWS Management Console automatically adds a parameter mapping from `method.r - 11. Choose **Save**. + * the multi-value method request query string, named `methodRequestQueryParam`, into the integration request query string, named `integrationQueryParam` @@ -46 +54,0 @@ The AWS Management Console automatically adds a parameter mapping from `method.r - 12. Redeploy your API for the changes to take effect. @@ -51,109 +59 @@ The AWS Management Console automatically adds a parameter mapping from `method.r -The following steps show you how to verify that your parameter mapping was successful. - -###### (Optional) Test your parameter mapping - - 1. Choose the **Test** tab. You might need to choose the right arrow button to show the tab. - - 2. For headers, enter `puppies:true`. - - 3. Choose **Test**. - - 4. In the **Logs** , the result should look like the following: - - Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true} - Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations: - Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets - Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344} - -The request header parameter has changed from `puppies` to `DogsAge0`. - - - - -AWS CloudFormation - - -In this example, you use the [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) property to import an OpenAPI definition file into API Gateway. - - - AWSTemplateFormatVersion: 2010-09-09 - Resources: - Api: - Type: 'AWS::ApiGateway::RestApi' - Properties: - Body: - openapi: 3.0.1 - info: - title: ParameterMappingExample - version: "2025-02-04T00:30:41Z" - paths: - /pets: - get: - parameters: - - name: puppies - in: header - schema: - type: string - responses: - "200": - description: 200 response - x-amazon-apigateway-integration: - httpMethod: GET - uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets - responses: - default: - statusCode: "200" - requestParameters: - integration.request.header.DogsAge0: method.request.header.puppies - passthroughBehavior: when_no_match - type: http - ApiGatewayDeployment: - Type: 'AWS::ApiGateway::Deployment' - DependsOn: Api - Properties: - RestApiId: !Ref Api - ApiGatewayDeployment20250219: - Type: 'AWS::ApiGateway::Deployment' - DependsOn: Api - Properties: - RestApiId: !Ref Api - Stage: - Type: 'AWS::ApiGateway::Stage' - Properties: - DeploymentId: !Ref ApiGatewayDeployment20250219 - RestApiId: !Ref Api - StageName: prod - -OpenAPI - - - - { - "openapi" : "3.0.1", - "info" : { - "title" : "ParameterMappingExample", - "version" : "2025-02-04T00:30:41Z" - }, - "paths" : { - "/pets" : { - "get" : { - "parameters" : [ { - "name" : "puppies", - "in" : "header", - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "200" : { - "description" : "200 response" - } - }, - "x-amazon-apigateway-integration" : { - "httpMethod" : "GET", - "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", - "responses" : { - "default" : { - "statusCode" : "200" - } - }, + ... @@ -161,30 +60,0 @@ OpenAPI - "integration.request.header.DogsAge0" : "method.request.header.puppies" - }, - "passthroughBehavior" : "when_no_match", - "type" : "http" - } - } - } - } - } - -## Example 2: Map multiple method request parameters to different integration request parameters -