AWS apigateway documentation change
Summary
Restructured content about API mappings, clarified routing behavior, updated console navigation steps, and improved example formatting. Added explicit mention of TLS 1.2 requirement for multi-level mappings with Regional domains.
Security assessment
The change maintains but does not introduce new security documentation. While TLS 1.2 is mentioned as a requirement for multi-level mappings, this was already implied in the original text. No specific vulnerability or security incident is addressed. The routing mode requirement and path stripping clarification are operational details without direct security implications.
Diff
diff --git a/apigateway/latest/developerguide/rest-api-mappings.md b/apigateway/latest/developerguide/rest-api-mappings.md index c1b01bfcd..8839afa08 100644 --- a//apigateway/latest/developerguide/rest-api-mappings.md +++ b//apigateway/latest/developerguide/rest-api-mappings.md @@ -5 +5 @@ -Routing API requestsRestrictionsCreate an API mapping +Incoming requests to your custom domain nameMapping API requestsRestrictionsCreate an API mapping @@ -7 +7 @@ Routing API requestsRestrictionsCreate an API mapping -# Map API stages to a custom domain name for REST APIs +# Use API mappings to connect API stages to a custom domain name for REST APIs @@ -11 +11 @@ You use API mappings to connect API stages to a custom domain name. This sends t -An API mapping specifies an API, a stage, and optionally a path to use for the mapping. For example, you can map the `production` stage of an API to `https://api.example.com/orders`. +An API mapping specifies an API, a stage, and optionally a path to use for the mapping. For example, you can map `https://api.example.com/orders` to the `production` stage of an API. @@ -17 +17 @@ Before you create an API mapping, you must have an API, a stage, and a custom do -## Routing API requests +## Incoming requests to your custom domain name @@ -19 +19 @@ Before you create an API mapping, you must have an API, a stage, and a custom do -You can configure API mappings with multiple levels, for example `orders/v1/items` and `orders/v2/items`. +When you map a custom domain name to a stage of your API, API Gateway strips the incoming base path. This removes the mapped base path from the invocation to the API. For instance, if your base path mapping was `https://api.example.com/orders/shop/5` to the `test` stage, and you used the following request, `https://api.example.com/orders/shop/5/hats`, API Gateway would invoke the `/hats` resource of the `test` stage of your API, not the `orders/shop/5/hats` resource. @@ -21,9 +21 @@ You can configure API mappings with multiple levels, for example `orders/v1/item -###### Note - -To configure API mappings with multiple levels, you must use a Regional custom domain name with the TLS 1.2 security policy. - -For API mappings with multiple levels, API Gateway routes requests to the API mapping that has the longest matching path. API Gateway considers only the paths configured for API mappings, and not API routes, to select the API to invoke. If no path matches the request, API Gateway sends the request to the API that you've mapped to the empty path `(none)`. - -For custom domain names that use API mappings with multiple levels, API Gateway routes requests to the API mapping that has the longest matching prefix. - -For example, consider a custom domain name `https://api.example.com` with the following API mappings: +## Mapping API requests @@ -31 +23 @@ For example, consider a custom domain name `https://api.example.com` with the fo - 1. `(none)` mapped to API 1. +The following explains how API Gateway evaluates API mappings. @@ -33 +25 @@ For example, consider a custom domain name `https://api.example.com` with the fo - 2. `orders` mapped to API 2. +You can create an API mapping using single-level mappings, such an API mapping from `orders` to the `beta` stage of an API and an API mapping from `shipping` to the `alpha` stage of an API. For a Regional custom domain names with the TLS 1.2 security policy, API Gateway supports multi-level API mappings. You can create an API mapping from `orders/v1/items` to the `alpha` stage of an API and `orders/v2/items` to the `beta` stage of an API. When you create a mapping with multiple levels, API Gateway sends requests to the API mapping that has the longest matching path. @@ -35,5 +27 @@ For example, consider a custom domain name `https://api.example.com` with the fo - 3. `orders/v1/items` mapped to API 3. - - 4. `orders/v2/items` mapped to API 4. - - 5. `orders/v2/items/categories` mapped to API 5. +You can create an API mapping to the empty path `(none)`. If no path matches the request, API Gateway sends the request to the empty path `(none)`. @@ -40,0 +29 @@ For example, consider a custom domain name `https://api.example.com` with the fo +In this example, the custom domain name `https://api.example.com` has the following API mappings. @@ -41,0 +31,7 @@ For example, consider a custom domain name `https://api.example.com` with the fo +API Mapping | Selected API +---|--- +`(none)` | API 1 +`orders` | API 2 +`orders/v1/items` | API 3 +`orders/v2/items` | API 4 +`orders/v1/items/categories` | API 5 @@ -42,0 +39 @@ For example, consider a custom domain name `https://api.example.com` with the fo +The following table shows how API Gateway applies the previous API mappings to example requests. @@ -46,7 +43,7 @@ Request | Selected API | Explanation -`https://api.example.com/orders` | `API 2` | The request exactly matches this API mapping. -`https://api.example.com/orders/v1/items` | `API 3` | The request exactly matches this API mapping. -`https://api.example.com/orders/v2/items` | `API 4` | The request exactly matches this API mapping. -`https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway chooses the mapping that has the longest matching path. The `123` at the end of the request doesn't affect the selection. -`https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway chooses the mapping that has the longest matching path. -`https://api.example.com/customers` | `API 1` | API Gateway uses the empty mapping as a catch-all. -`https://api.example.com/ordersandmore` | `API 2` | API Gateway chooses the mapping that has the longest matching prefix. For a custom domain name configured with single-level mappings, such as only `https://api.example.com/orders` and `https://api.example.com/`, API Gateway would choose `API 1`, as there is no matching path with `ordersandmore`. +`https://api.example.com/orders` | API 2 | The request exactly matches this API mapping. +`https://api.example.com/orders/v1/items` | API 3 | The request exactly matches this API mapping. +`https://api.example.com/orders/v2/items` | API 4 | The request exactly matches this API mapping. +`https://api.example.com/orders/v1/items/123` | API 3 | API Gateway chooses the mapping that has the longest matching path. The `123` at the end of the request doesn't affect the selection. See Incoming requests to your custom domain name. +`https://api.example.com/orders/v2/items/categories/5` | API 5 | API Gateway chooses the mapping that has the longest matching path. +`https://api.example.com/customers` | API 1 | API Gateway uses the empty mapping as a catch-all. +`https://api.example.com/ordersandmore` | API 2 | API Gateway chooses the mapping that has the longest matching prefix. For a custom domain name configured with single-level mappings, such as only `https://api.example.com/orders` and `https://api.example.com/`, API Gateway would choose `API 1`, as there is no matching path with `ordersandmore`. @@ -77 +74 @@ Request | Selected API | Explanation -To create an API mapping, you must first create a custom domain name, API, and stage. For information about creating a custom domain name, see [Set up a Regional custom domain name in API Gateway](./apigateway-regional-api-custom-domain-create.html). +To create an API mapping, you must first create a custom domain name, API, and stage. Your custom domain name must have a routing mode set to either `ROUTING_RULE_THEN_API_MAPPING` or `API_MAPPING_ONLY`. For information about how to set the routing mode, see [Set the routing mode for your custom domain name](./set-routing-mode.html). @@ -90 +87 @@ AWS Management Console - 4. On the **API mappings** tab, choose **Configure API mappings**. + 4. On the **Routing details** tab, choose **Configure API mappings**. @@ -140 +137 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -IP address types for custom domain names in API Gateway +Troubleshooting issues with routing rules @@ -142 +139 @@ IP address types for custom domain names in API Gateway -Choose a security policy +IP address types for custom domain names in API Gateway