Custom domain names for WebSocket 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
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.
-
If you map a custom domain name to a WebSocket API, you can't map it to a REST API or an HTTP API.
-
Only Regional custom domain names are supported.
-
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.
Prerequisites
The following are prerequisites for 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 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
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 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. 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.
You can use the $context.domainName and
$context.domainPrefix context variables to determine the domain name
that a client used to call your API. To learn more about context variables, see API Gateway mapping template and access
logging variable reference.
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
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. Next, you create a Regional custom domain name. For more information, see Set up a Regional custom domain name in API Gateway.
