Set up a Regional custom
domain name in API Gateway
Use a Regional custom domain name to create a user-friendly API base URL. With a Regional custom domain name,
you can map HTTP and REST API stages to the same custom domain name and use mutual TLS authentication.
Considerations
The following are considerations for your Regional custom domain name.
-
You must provide a Region-specific ACM certificate. This certificate must be in the same Region as your API. For more
information about creating or uploading a custom domain name certificate, see Get certificates ready in AWS Certificate Manager.
-
When you create a Regional custom domain name (or migrate one) with an ACM certificate,
API Gateway creates a service-linked role in your account. The
service-linked role is required to attach your ACM certificate to your Regional endpoint.
The role is named AWSServiceRoleForAPIGateway and will have the
APIGatewayServiceRolePolicy managed policy attached to it. For more
information about use of the service-linked role, see Using Service-Linked Roles.
-
After your create your Regional custom domain name, you must create a DNS record to point the custom domain name to the Regional domain
name. This enables the traffic that is bound to the custom domain name to be routed to
the API's Regional hostname. The DNS record can be the CNAME or "A" type.
Create a Regional custom domain name
The following procedure shows how to create a Regional custom domain name. After you complete this procedure,
you must create a DNS record to point the custom domain name to the Regional domain name.
- AWS Management Console
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
-
Choose Custom domain names from the main navigation
pane.
-
Choose Create.
-
For Domain name, enter a domain name.
-
For Minimum TLS version, select a version.
-
Under Endpoint configuration, for API endpoint type, choose Regional.
-
Choose an ACM certificate. The certificate must be in the same Region as the API.
-
Choose Create.
- AWS CLI
-
The following create-domain-name
command can be used to create a custom domain name:
aws apigatewayv2 create-domain-name \
--domain-name 'regional.example.com' \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2
:123456789012
:certificate/123456789012-1234-1234-1234-12345678
If successful, the call returns a result similar to the following:
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "regional.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:123456789012
:certificate/123456789012-1234-1234-1234-12345678
",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
]
}
The DomainNameConfigurations
property value returns the Regional
API's hostname. You must create a DNS record to point your custom domain name to
this Regional domain name. This enables the traffic that is bound to the custom
domain name to be routed to this Regional API's hostname.
Create a DNS record for your Regional custom domain name
The following procedure shows how to create a DNS record to point your custom domain name your newly created Regional domain name.
- AWS Management Console
To use the AWS Management Console, follow the Route 53 documentation on configuring Route 53 to route traffic to API Gateway.
- AWS CLI
To configure your DNS records to map the Regional custom domain name to its
hostname of the given hosted zone ID, first create a JSON file that contains the
configuration for setting up a DNS record for the Regional domain name.
The
following setup-dns-record.json
shows how to create a DNS A
record to map a
Regional custom domain name (regional.example.com
) to its Regional
hostname (d-numh1z56v6.execute-api.us-west-2.amazonaws.com
)
provisioned as part of the custom domain name creation. The DNSName
and HostedZoneId
properties of AliasTarget
can take
the regionalDomainName
and regionalHostedZoneId
values, respectively, of the custom domain name. You can also get the Regional
Route 53 Hosted Zone IDs in Amazon API Gateway Endpoints and Quotas.
{
"Changes": [
{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "regional.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"EvaluateTargetHealth": false
}
}
}
]
}
The following change-resource-record-sets
shows how to create a DNS record for your Regional custom domain name:
aws route53 change-resource-record-sets \
--hosted-zone-id Z2OJLYMUO9EFXC \
--change-batch file://path/to/your/setup-dns-record.json
Replace thehosted-zone-id
with the Route 53 Hosted
Zone ID of the DNS record set in your account. The change-batch
parameter value points to a JSON file
(setup-dns-record.json
) in a folder
(path/to/your
).
Create a base path mapping for your Regional custom domain name
After your create a DNS record, you create a base path mapping to map your API to the custom domain name. For
example, you can map the stage test
for the API ID of abc123
to the custom domain name
regional.example.com
using the API mapping key of myApi
. This maps the API
https://abcd1234.execute-api.us-west-2.amazonaws.com/test
to
https://regional.example.com/myApi
.
- AWS Management Console
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
-
Choose a custom domain name.
-
Choose Configure API mappings.
-
Choose Add new mapping.
-
Specify the API, Stage, and Path for the mapping.
-
Choose Save.
- AWS CLI
The following create-api-mapping
command can be used to create a base path mapping:
aws apigatewayv2 create-api-mapping \
--domain-name 'regional.example.com' \
--api-mapping-key 'myApi' \
--api-id abcd1234 \
--stage 'test'
As a result, the base URL using the custom domain name for the API that is
deployed in the stage becomes
https://regional.example.com/myAPI
.
With a Regional custom domain name, you can create an API mapping with multiple levels, such as
https://regional.example.com/orders/v1/items/123
. You can also map HTTP and REST API stages to the
same custom domain name. For more information, see Map API stages to a custom domain name for REST APIs.