AWS apigateway documentation change
Summary
Restructured documentation to focus on mapping templates, removed proxy integration recommendations, added links to related topics, and clarified technical details about VTL/JSONPath usage
Security assessment
Changes focus on technical implementation details and documentation structure. No evidence of addressing vulnerabilities or security incidents. Removed proxy integration recommendation doesn't explicitly relate to security
Diff
diff --git a/apigateway/latest/developerguide/rest-api-data-transformations.md b/apigateway/latest/developerguide/rest-api-data-transformations.md index f50fbe55a..b92460273 100644 --- a/apigateway/latest/developerguide/rest-api-data-transformations.md +++ b/apigateway/latest/developerguide/rest-api-data-transformations.md @@ -5,2 +4,0 @@ -Choose between parameter mapping and mapping template transformations - @@ -9,5 +7 @@ Choose between parameter mapping and mapping template transformations -###### Note - -This section explains features that you use with a non-proxy integration. However, we recommend that when possible, you use a proxy integration for your REST API. A proxy integration has a streamlined integration setup and can evolve with the backend without having to tear down the existing setup. For more information, see [Choose an API Gateway API integration type](./api-gateway-api-integration-types.html). - -If you use a non-proxy integration, you can use two features of API Gateway to transform your method request and your integration response. You might transform your method request if it takes a different payload format than the integration request payload. You might transform your integration response if it returns a different payload format than the format you need to return in the method response. For more information about the request lifecycle, see [Example resource for a REST API](./rest-api-develop.html#rest-api-develop-example). +In API Gateway, an API's method request can take a payload in a different format from the integration request payload. Similarly, the backend may return an integration response payload different from the method response payload. You can map URL path parameters, URL query string parameters, HTTP headers, and the request body across API Gateway using mapping templates. @@ -15 +9 @@ If you use a non-proxy integration, you can use two features of API Gateway to t -The following example shows a data transformation where for the header `"x-version:beta"`, the `x-version` header parameter is transformed into the `app-version` header parameter. The data transformation from `x-version` to `app-version` occurs in the integration request. That way, the integration endpoint receives the transformed header parameter value. When the integration endpoint returns a status code, the status code is transformed from `200` to `204` before the method response. +A _mapping template_ is a script expressed in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) and applied to the payload using [JSONPath expressions](https://goessner.net/articles/JsonPath/). @@ -17 +11 @@ The following example shows a data transformation where for the header `"x-versi - +The payload can have a _data model_ according to the [JSON schema draft 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). To learn more about models, see [Data models for REST APIs](./models-mappings-models.html). @@ -19,6 +13 @@ The following example shows a data transformation where for the header `"x-versi -To create a data transformation, you can use the following features: - -**Parameter mapping** - - -In parameter mapping, you can modify integration request URL path parameters, URL query string parameters, or HTTP header values, but you can't modify the integration request payload. You can also modify HTTP response header values. Use parameter mapping to create static header values for cross origin resource sharing (CORS). Parameter mapping doesn't require any scripting in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). For more information, see [Parameter mapping for REST APIs in API Gateway](./rest-api-parameter-mapping.html). +###### Note @@ -26 +15 @@ In parameter mapping, you can modify integration request URL path parameters, UR -**Mapping template transformations** +You don't have to define any model to create a mapping template, but you must define a model in order to have API Gateway to generate a SDK or to turn on request body validation for your API. @@ -27,0 +17 @@ In parameter mapping, you can modify integration request URL path parameters, UR +###### Topics @@ -29 +19 @@ In parameter mapping, you can modify integration request URL path parameters, UR -In mapping template transformations, you use a mapping template to map URL path parameters, URL query string parameters, HTTP headers, and the integration request or integration response body. A _mapping template_ is a script expressed in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) using [JSONPath expressions](https://goessner.net/articles/JsonPath/) and applied to the payload based on the `Content-type` header. + * [Mapping templates for REST APIs](./models-mappings.html) @@ -31 +21 @@ In mapping template transformations, you use a mapping template to map URL path -With a mapping template, you can do the following: + * [Set up data transformations in API Gateway](./set-up-data-transformations-in-api-gateway.html) @@ -33 +23 @@ With a mapping template, you can do the following: - * Select which data to send using integration with AWS services, such as Amazon DynamoDB or Lambda functions, or HTTP endpoints. For more information, see [Tutorial: Modify the integration request and response for integrations to AWS services](./set-up-data-transformations-in-api-gateway.html). + * [Use a mapping template to override an API's request and response parameters and status codes](./apigateway-override-request-response-parameters.html) @@ -35 +25 @@ With a mapping template, you can do the following: - * Conditionally override an API's integration request and integration response parameters, create new header values, and override status codes. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](./apigateway-override-request-response-parameters.html). + * [Set up request and response data mappings using the API Gateway console](./how-to-method-settings-execution-console.html) @@ -36,0 +27 @@ With a mapping template, you can do the following: + * [Example data models and mapping templates for API Gateway](./rest-api-develop-models-mapping-examples.html) @@ -37,0 +29 @@ With a mapping template, you can do the following: + * [Amazon API Gateway API request and response data mapping reference](./request-response-data-mappings.html) @@ -38,0 +31 @@ With a mapping template, you can do the following: + * [API Gateway mapping template and access logging variable reference](./api-gateway-mapping-template-reference.html) @@ -40 +32,0 @@ With a mapping template, you can do the following: -You can also specify the behavior of your API when an integration request body has `Content-type` header with no matching mapping templates. This is called integration passthrough behavior. For more information, see [Method request behavior for payloads without mapping templates for REST APIs in API Gateway](./integration-passthrough-behaviors.html). @@ -42 +33,0 @@ You can also specify the behavior of your API when an integration request body h -## Choose between parameter mapping and mapping template transformations @@ -44 +34,0 @@ You can also specify the behavior of your API when an integration request body h -We recommend that you use parameter mapping to transform your data when possible. If your API requires you to change the body, or requires you to perform conditional overrides and modifications based on the incoming integration request or integration response, and you can't use a proxy integration, use mapping template transformations. @@ -54 +44 @@ AWS CloudFormation template of a sample API with basic request validation -Parameter mapping +Mapping templates for REST APIs