AWS apigateway documentation change
Summary
Restructured documentation to focus on use cases, considerations, and mapping template reference. Removed detailed step-by-step examples and replaced with general guidance and external references.
Security assessment
The changes reorganize content and add general guidance about parameter overrides but do not address specific security vulnerabilities or introduce new security features. Mentions of 5XX errors and proxy integration limitations are operational considerations, not direct security issues.
Diff
diff --git a/apigateway/latest/developerguide/apigateway-override-request-response-parameters.md b/apigateway/latest/developerguide/apigateway-override-request-response-parameters.md index d551b6c7a..8e12df596 100644 --- a/apigateway/latest/developerguide/apigateway-override-request-response-parameters.md +++ b/apigateway/latest/developerguide/apigateway-override-request-response-parameters.md @@ -5 +5 @@ -Example 1: Override the status code based on the integration bodyExample 2: Override the request header and create new headers +Use cases for overriding your API's request and response parameters and status codesConsiderations for overriding your API's request and response parameters and status codesMapping template override reference @@ -7 +7 @@ Example 1: Override the status code based on the integration bodyExample 2: Over -# Override your API's request and response parameters and status codes for REST APIs in API Gateway +# Use a mapping template to override an API's request and response parameters and status codes @@ -9 +9 @@ Example 1: Override the status code based on the integration bodyExample 2: Over -You can use mapping template transformations to override any type of request parameter, response header, or response status code. You use a mapping template to do the following: +Standard API Gateway [parameter and response code mapping templates](./models-mappings.html#models-mappings-mappings) allow you to map parameters one-to-one and map a family of integration response status code, matched by a regular expression, to a single response status code. Mapping template overrides let you do the following. @@ -24 +24 @@ You can use mapping template transformations to override any type of request par -Overrides are final. An override may only be applied to each parameter once. If you try to override the same parameter multiple times, API Gateway returns a `5XX` response. If you must override the same parameter multiple times throughout the template, we recommend creating a variable and applying the override at the end of the template. The template is applied only after the entire template is parsed. +Any type of request parameter, response header, or response status code may be overridden. @@ -26 +26 @@ Overrides are final. An override may only be applied to each parameter once. If -## Example 1: Override the status code based on the integration body +## Use cases for overriding your API's request and response parameters and status codes @@ -28 +28 @@ Overrides are final. An override may only be applied to each parameter once. If -The following example use the [example API](./api-gateway-create-api-from-example.html) to override the status code based on the integration response body. +In your API, you might use a mapping template override for your API to do the following. @@ -30 +30 @@ The following example use the [example API](./api-gateway-create-api-from-exampl -AWS Management Console + * To create a new header (or overwrite an existing header) as a concatenation of two parameters @@ -31,0 +32 @@ AWS Management Console + * To override the response code to a success or failure code based on the contents of the body @@ -33 +34 @@ AWS Management Console -###### To override a status code based on the integration response body + * To conditionally remap a parameter based on its contents or the contents of some other parameter @@ -35 +36 @@ AWS Management Console - 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). + * To iterate over the contents of a json body and remap key value pairs to headers or query strings @@ -37 +37,0 @@ AWS Management Console - 2. Choose **Create API**. @@ -39 +38,0 @@ AWS Management Console - 3. For **REST API** , choose **Build**. @@ -41 +39,0 @@ AWS Management Console - 4. For **API details** , choose **Example API**. @@ -43 +41 @@ AWS Management Console - 5. Choose **Create API**. +## Considerations for overriding your API's request and response parameters and status codes @@ -45 +43 @@ AWS Management Console -API Gateway creates an example pet store API. To retrieve information about a pet, you use the API method request of `GET /pets/{petId}`, where `{petId}` is a path parameter corresponding to an ID number for a pet. +The following considerations might impact your use of mapping template overrides. @@ -47 +45 @@ API Gateway creates an example pet store API. To retrieve information about a pe -In this example, you override the `GET` method's response code to `400` when an error condition is detected. + * Mapping template overrides cannot be used with proxy integration endpoints, which lack data mappings. For more information about integration types, see [Choose an API Gateway API integration type](./api-gateway-api-integration-types.html). @@ -49 +47 @@ In this example, you override the `GET` method's response code to `400` when an - 6. In the **Resources** tree, choose the `GET` method under `/{petId}`. + * Overrides are final. An override may only be applied to each parameter once. If you try to override the same parameter multiple times, API Gateway returns a `5XX` response. If you must override the same parameter multiple times throughout the template, we recommend creating a variable and applying the override at the end of the template. The template is applied only after the entire template is parsed. For more information, see [Override an API's request parameters and headers using the AWS Management Console](./apigateway-override-request-response-examples.html#apigateway-override-request-response-parameters-override-request) @@ -51 +48,0 @@ In this example, you override the `GET` method's response code to `400` when an - 7. First, you test the current implementation of the API. @@ -53 +49,0 @@ In this example, you override the `GET` method's response code to `400` when an -Choose the **Test** tab. You might need to choose the right arrow button to show the tab. @@ -55 +50,0 @@ Choose the **Test** tab. You might need to choose the right arrow button to show - 8. For **petId** , enter `-1`, and then choose **Test**. @@ -57 +52 @@ Choose the **Test** tab. You might need to choose the right arrow button to show -The **Response body** indicates an out-of-range error: +## Mapping template override reference @@ -59,8 +54 @@ The **Response body** indicates an out-of-range error: - { - "errors": [ - { - "key": "GetPetRequest.petId", - "message": "The value is out of range." - } - ] - } +To create a mapping template override, use one or more of the following [$context variables](./api-gateway-mapping-template-reference.html#context-variable-reference) in a [mapping template](./models-mappings.html#models-mappings-mappings): @@ -68 +56,5 @@ The **Response body** indicates an out-of-range error: -In addition, the last line under **Logs** ends with: `Method completed with status: 200`. +Request body mapping template | Response body mapping template +---|--- +`$context.requestOverride.header.`header_name`` | `$context.responseOverride.header.`header_name`` +`$context.requestOverride.path.`path_name`` | `$context.responseOverride.status` +`$context.requestOverride.querystring.`querystring_name`` | None @@ -70,414 +62 @@ In addition, the last line under **Logs** ends with: `Method completed with stat -The integration was completed successfully, but there was an error. Now you'll override the status code based on the integration response. - - 9. On the **Integration response** tab, for the **Default - Response** , choose **Edit**. - - 10. Choose **Mapping templates**. - - 11. Choose **Add mapping template**. - - 12. For **Content type** , enter `application/json`. - - 13. For **Template body** , enter the following: - - #set($inputRoot = $input.path('$')) - $input.json("$") - #if($inputRoot.toString().contains("error")) - #set($context.responseOverride.status = 400) - #end - -This mapping template uses the `$context.responseOverride.status` variable to override the status code to `400` if the integration response contains the string `error`. - - 14. Choose **Save**. - - 15. Choose the **Test** tab. - - 16. For **petId** , enter `-1`. - - 17. In the results, the **Response Body** indicates an out-of-range error: - - { - "errors": [ - { - "key": "GetPetRequest.petId", - "message": "The value is out of range." - } - ] - } - -However, the last line under **Logs** now ends with: `Method completed with status: 400`. - - - - -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: PetStore Example 1 - description: Example pet store API. - version: "2025-01-14T00:13:18Z" - paths: - /pets/{petId}: - get: - parameters: - - name: petId - in: path - required: true - schema: - type: string - responses: - "200": - description: 200 response - x-amazon-apigateway-integration: - httpMethod: GET - uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId} - responses: - default: - statusCode: "200" - responseTemplates: - application/json: |- - #set($inputRoot = $input.path('$')) - $input.json("$") - #if($inputRoot.toString().contains("error")) - #set($context.responseOverride.status = 400) - #end - requestParameters: - integration.request.path.petId: method.request.path.petId - passthroughBehavior: when_no_match - type: http - components: - schemas: - Pet: - type: object - properties: - id: - type: integer - type: - type: string - price: - type: number - 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 - -