How do I define a custom domain name for my API Gateway API?

Last updated: 2020-05-22

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

Short Description

In API Gateway, you can create either an edge-optimized custom domain name or a Regional custom domain name. There are some key differences between these types of custom domain names:

Custom domain name type API type Target endpoint SSL/TLS certificate Domain name
Edge-optimized Only REST APIs can use edge-optimized custom domain names. An Amazon CloudFront distribution with a format similar to examplek7xoo.cloudfront.net. The certificate must be in the US East (N. Virginia) (us-east-1) AWS Region. The domain name must be unique. (It's attached to a CloudFront distribution endpoint as a CNAME, and you can't associate a CNAME with more than one CloudFront distribution.)
Regional All these API types can use Regional custom domain names:
REST APIs
WebSocket APIs
HTTP APIs
A Regional API endpoint with a format similar to examplevpz7.execute-api.us-west-2.amazonaws.com. The certificate must be in the same Region as your API. The domain name can be shared by other Regional custom domain names in different Regions.

Also, note these key differences for domain name mapping:

Resolution

Request or import an SSL/TLS certificate

Before creating 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 Getting certificates ready in AWS Certificate Manager.

When requesting or importing the certificate, note the following requirements:

  • To pass domain validation checks, the certificate must include the custom domain name as an alternate domain name. For more information about validation checks with CloudFront distributions (for edge-optimized custom domain names), see Continually Enhancing Domain Security on Amazon CloudFront. There are similar validation checks for Regional custom domain names.
  • For an edge-optimized custom domain name, the ACM certificate must be in the US East (N. Virginia) (us-east-1) Region.
  • For a Regional custom domain name, the ACM certificate must be in the same Region as your API.

Create the custom domain name

Depending on your API Gateway API type, choose from the following for instructions to create a custom domain name:

Test the custom domain name

  1. Run a curl command on the domain name using the base path mapping that you specified when you created the custom domain name.
    Note: For more information about curl, see the cURL project website.
  2. 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 article help?


Do you need billing or technical support?