How do I configure a custom domain endpoint for multiple API Gateway APIs behind a CloudFront web distribution?

Resolution

Create the custom domain name and associate your APIs

Create a custom domain name for your APIs on API Gateway. To map multiple APIs to the same domain with different base paths, see the following:

• For REST APIs, see Setting up custom domain names for REST APIs.
• For HTTP APIs, see Setting up custom domain names for HTTP APIs.
• For WebSocket APIs, see Setting up custom domain names for WebSocket APIs.

After you create a custom domain name in API Gateway, update your DNS record to map the custom domain name to your API endpoint. To update DNS in Amazon Route 53, see Routing traffic to an Amazon API Gateway API by using your domain name.

The following example uses a REST API Regional custom domain name setup:

• https://restapiId1.execute-api.us-west-2.amazonaws.com/stage1/example1/home
• https://restapiId2.execute-api.us-west-2.amazonaws.com/stage2/example2/home

Example custom domain base path mapping:

• The base path /api1 maps to the stage1 stage of the REST API with restapiId1 ID.
• The base path /api2 maps to the stage2 stage of the REST API with restapiId2 ID.

Example custom domain URLs:

• https://apigw.customdomain.com/api1/example1/home
• https://apigw.customdomain.com/api2/example2/home

Create a CloudFront web distribution

To create a distribution, complete the following steps:

1. Open the CloudFront console.
2. Choose Create distribution.
3. For Origin domain, enter your API Gateway custom domain name. For example, apigw.customdomain.com.
4. For Origin path, keep blank.
   Note: If the base path in the origin path is incorrect, then CloudFront returns a 403 Forbidden error with Missing Authentication Token. For more information, see How do I troubleshoot API Gateway REST API endpoint 403 "Missing Authentication Token" errors?
5. For Minimum origin SSL protocol, choose TLSv1.2.
6. For Origin protocol policy, choose HTTPS only.
7. (Optional) To add custom headers to your origin, choose Add header, and enter your Header name and Value.
8. For Origin request policy, select AllViewerExceptHostHeader to forward all request parameters.
9. (Optional) To deactivate cache, for the Cache policy, choose CachingDisabled.
10. For Viewer protocol policy, choose HTTPS only or Redirect HTTP to HTTPS as needed.
11. Choose Create distribution.

After you create a distribution, the distribution status changes from InProgress to Deployed.

Test your CloudFront web distribution

Complete the following steps:

1. Open the CloudFront console.
2. Take note of the Domain Name of your web distribution. For example, a222222bcdefg5.cloudfront.net.
3. Test your distribution.

A successful test returns an HTTP 200 OK response. Propagation will take up to 24 hours. If the request doesn't return a response, then the CloudFront DNS record is still in progress. If the distribution hasn't deployed, then you might get an HTTP 5xx error. Other HTTP 4xx errors can occur if DNS propagation is incomplete.

After you create a CloudFront distribution, you can request two APIs from a single CloudFront distribution and your API Gateway custom domain name.

To forward incoming authorization headers for your CloudFront web distribution, see How do I set up API Gateway with my own CloudFront distribution?

Related information

API endpoint types for REST APIs in API Gateway