Map API stages to a custom domain name for REST APIs
You use API mappings to connect API stages to a custom domain name. After you create a domain name and configure DNS records, you use API mappings to send traffic to your APIs through your custom domain name.
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
.
You can map HTTP and REST API stages to the same custom domain name.
Before you create an API mapping, you must have an API, a stage, and a custom domain name. To learn more about creating a custom domain name, see Set up a Regional custom domain name in API Gateway.
Routing API requests
You can configure API mappings with multiple levels, for example orders/v1/items
and
orders/v2/items
.
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:
-
(none)
mapped to API 1. -
orders
mapped to API 2. -
orders/v1/items
mapped to API 3. -
orders/v2/items
mapped to API 4. -
orders/v2/items/categories
mapped to API 5.
Request | Selected API | Explanation |
---|---|---|
|
|
The request exactly matches this API mapping. |
|
|
The request exactly matches this API mapping. |
|
|
The request exactly matches this API mapping. |
|
|
API Gateway chooses the mapping that has the longest matching path. The |
|
|
API Gateway chooses the mapping that has the longest matching path. |
|
|
API Gateway uses the empty mapping as a catch-all. |
|
|
API Gateway chooses the mapping that has the longest matching prefix. For a custom domain name configured with
single-level mappings, such as only |
Restrictions
-
In an API mapping, the custom domain name and mapped APIs must be in the same AWS account.
-
API mappings must contain only letters, numbers, and the following characters:
$-_.+!*'()/
. -
The maximum length for the path in an API mapping is 300 characters.
-
You can have 200 API mappings with multiple levels for each domain name.
-
You can only map HTTP APIs to a regional custom domain name with the TLS 1.2 security policy.
-
You can't map WebSocket APIs to the same custom domain name as an HTTP API or REST API.
Create an API mapping
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.
For example AWS Serverless Application Model templates that create all resources, see
Sessions With
SAM