I want to use a custom domain name for my API in Amazon API Gateway instead of using the default base URL. How can I set up a custom domain name for my API?

To set up a custom domain name for your API in API Gateway, you can create either an edge-optimized domain name or a regional custom domain name. Differences between these types of domain names include:

  • Target endpoint: The target endpoint of an edge-optimized domain name has a format similar to examplek7xoo.cloudfront.net because the endpoint is an Amazon CloudFront distribution. In comparison, the target endpoint of a regional custom domain name has a format similar to examplevpz7.execute-api.us-west-2.amazonaws.com because the endpoint isn't attached to a CloudFront distribution.
  • Unique domain name: An edge-optimized custom domain name must be unique because it's attached to the CloudFront distribution endpoint as a CNAME—you can't associate a CNAME to more than one CloudFront distribution. In comparison, you can create two identical regional custom domain names when they're in two separate AWS Regions.

For more information on the types of custom domain names, see Set up Custom Domain Name for an API in API Gateway.

Request or import an SSL/TLS certificate

Before you create a custom domain name for your API, you must request an SSL/TLS certificate from AWS Certificate Manager (ACM), or import an SSL/TLS certificate into ACM. For more information, see Get Certificates Ready in AWS Certificate Manager.

If you want to create an edge-optimized custom domain name, the certificate must be in the US East (N. Virginia) (us-east-1) Region. If you want to create a regional custom domain name, the certificate must be in the same Region as your API.

Create the custom domain name

To create the custom domain name, use one of the following procedures:

Test the custom domain name

To test the new custom domain name, run a curl command on the domain name. You must make the request to the domain name using the base path mapping that you specified when you created the custom domain name. Then, verify that the response to the custom domain name is the same response that you receive when you invoke the API stage URL.


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2018-11-19