# Custom domain names for HTTP APIs in API Gateway
*Custom domain names* are simpler and more intuitive URLs that you can provide to your API users.
After deploying your API, you (and your customers) can invoke the API using the default base URL of the following format:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
where *api-id* is generated by API Gateway, *region* is the AWS Region, and *stage* is specified by you when deploying the API.
The hostname portion of the URL, `api-id.execute-api.region.amazonaws.com` refers to an API endpoint. The default API endpoint name is randomly generated, difficult to recall, and not user-friendly.
With custom domain names, you can set up your API's hostname, and choose a base path (for example, `myservice`) to map the alternative URL to your API. For example, a more user-friendly API base URL can become:
```
https://api.example.com/myservice
```
## Considerations
The following considerations might impact your use of a custom domain name.
+ A Regional custom domain name can be associated with REST APIs and HTTP APIs. You can use the API Gateway Version 2 APIs to create and manage Regional custom domain names for REST APIs.
+ For the minimum TLS version, only TLS 1.2 is supported.
+ You must create or update your DNS provider's resource record to map to your API endpoint. Without such a mapping, API requests bound for the custom domain name cannot reach API Gateway.
+ You can support an almost infinite number of domain names without exceeding the default quota by using a wildcard certificate. For more information, see [Wildcard custom domain names](#http-wildcard-custom-domain-names).
## Prerequisites
The following are prerequisites for creating a custom domain name.
### Register a domain name
You must have a registered internet domain name in order to set up custom domain names for your APIs. You can register your internet domain name using [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) or using a third-party domain registrar of your choice. Your custom domain name can be the name of a subdomain or the root domain (also known as the "zone apex") of a registered internet domain.
Your domain name must follow the [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) specification and can have a maximum of 63 octets per label and 255 octets in total.
### Certificates for custom domain names
Before setting up a custom domain name for an API, you must have an SSL/TLS certificate ready in ACM. If ACM is not available in the AWS Region where you are creating your custom domain name, you must import a certificate to API Gateway in that Region.
To import an SSL/TLS certificate, you must provide the PEM-formatted SSL/TLS certificate body, its private key, and the certificate chain for the custom domain name.
Each certificate stored in ACM is identified by its ARN. With certificates issued by ACM, you do not have to worry about exposing any sensitive certificate details, such as the private key. To use an AWS managed certificate for a domain name, you simply reference its ARN.
If your application uses certificate pinning, sometimes known as SSL pinning, to pin an ACM certificate, the application might not be able to connect to your domain after AWS renews the certificate. For more information, see [Certificate pinning problems](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) in the *AWS Certificate Manager User Guide*.
## Wildcard custom domain names
With wildcard custom domain names, you can support an almost infinite number of domain names without exceeding the [default quota](limits.md). For example, you could give each of your customers their own domain name, `customername.api.example.com`.
To create a wildcard custom domain name, specify a wildcard (`*`) as the first subdomain of a custom domain that represents all possible subdomains of a root domain.
For example, the wildcard custom domain name `*.example.com` results in subdomains such as `a.example.com`, `b.example.com`, and `c.example.com`, which all route to the same domain.
Wildcard custom domain names support distinct configurations from API Gateway's standard custom domain names. For example, in a single AWS account, you can configure `*.example.com` and `a.example.com` to behave differently.
To create a wildcard custom domain name, you must provide a certificate issued by ACM that has been validated using either the DNS or the email validation method.
**Note**
You can't create a wildcard custom domain name if a different AWS account has created a custom domain name that conflicts with the wildcard custom domain name. For example, if account A has created `a.example.com`, then account B can't create the wildcard custom domain name `*.example.com`.
If account A and account B share an owner, you can contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) to request an exception.
## Next steps for custom domain names
To set up a custom domain name for an HTTP API, you use documentation from the REST API section of the API Gateway Developer Guide.
First, specify a certificate for your custom domain name. For more information, see [Get certificates ready in AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Next, you create a Regional custom domain name. For more information, see [Set up a Regional custom domain name in API Gateway](apigateway-regional-api-custom-domain-create.md).
# Map API stages to a custom domain name for HTTP 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](apigateway-regional-api-custom-domain-create.md).
## Routing API requests
You can configure API mappings with multiple levels, for example `orders/v1/items` and `orders/v2/items`.
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:
1. `(none)` mapped to API 1.
1. `orders` mapped to API 2.
1. `orders/v1/items` mapped to API 3.
1. `orders/v2/items` mapped to API 4.
1. `orders/v2/items/categories` mapped to API 5.
| 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`. |
## 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. This limit doesn't include API mapping with single levels, such as `/prod`.
+ 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.
+ If you create an API mappings with multiple levels, API Gateway converts all header names to lowercase.
## 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](apigateway-regional-api-custom-domain-create.md).
For example AWS Serverless Application Model templates that create all resources, see [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) on GitHub.
------
#### [ AWS Management Console ]
**To create an API mapping**
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose **Custom domain names**.
1. Select a custom domain name that you've already created.
1. Choose **API mappings**.
1. Choose **Configure API mappings**.
1. Choose **Add new mapping**.
1. Enter an **API**, a **Stage**, and optionally a **Path**.
1. Choose **Save**.
------
#### [ AWS CLI ]
The following [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) command creates an API mapping. In this example, API Gateway sends requests to `api.example.com/v1/orders` to the specified API and stage.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
The following CloudFormation example creates an API mapping.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Disable the default endpoint for HTTP APIs
By default, clients can invoke your API by using the `execute-api` endpoint that API Gateway generates for your API. To ensure that clients can access your API only by using a custom domain name, disable the default `execute-api` endpoint. When you disable the default endpoint, it affects all stages of an API.
The following procedure shows how to disable the default endpoint for an HTTP API.
------
#### [ AWS Management Console ]
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose an HTTP API.
1. Choose your API's ID to open the **API details** page.
1. On **API details**, choose **Edit**.
1. For **Default endpoint**, select **Disable**.
1. Choose **Save**.
If you turn on automatic deployments for your stage, you do not need to redeploy your API for the change to take effect. Otherwise, you must redeploy your API.
1. (Optional) Choose **Deploy**, and then redeploy your API or create a new stage for the change to take effect.
------
#### [ AWS CLI ]
The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) command disables the default endpoint for an HTTP API:
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
After you disable the default endpoint, you must deploy your API for the change to take effect, unless automatic deployments are enabled.
The following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) command creates a deployment:
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# IP address types for custom domain names for HTTP APIs
When you create an API, you specify the type of IP addresses that can invoke your domain. You can choose IPv4 to resolve IPv4 addresses to invoke your domain, or you can choose dualstack to allow both IPv4 and IPv6 addresses to invoke your domain. We recommend that you set the IP address type to dualstack to alleviate IP space exhaustion or for your security posture. For more information about the benefits of a dualstack IP address type, see [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerations for IP address types
The following considerations might impact your use of IP address types.
+ The default IP address type for API Gateway custom domain names is IPv4.
+ Your custom domain name doesn't need to have the same IP address type for all APIs mapped to it. If you disable your default API endpoint, this might affect how callers can invoke your API.
## Change the IP address type of a custom domain name
You can change the IP address type by updating the domain’s endpoint configuration. You can update the domain's endpoint configuration by using the AWS Management Console, the AWS CLI, CloudFormation, or an AWS SDK.
------
#### [ AWS Management Console ]
**To change the IP address type of a custom domain name**
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose a public custom domain name.
1. Choose **Endpoint configuration**.
1. For IP address type, select either **IPv4** or **Dualstack**.
1. Choose **Save**.
------
#### [ AWS CLI ]
The following [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) command updates an API to have an IP address type of dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
The output will look like the following:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------