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

Resolution

Create the custom domain name for your REST API, HTTP API, or WebSocket API

If you haven't already done so, create your custom domain name, and then associate it with two different APIs.

Note: A custom domain name for a WebSocket API can't be mapped to REST APIs or HTTP APIs.

For REST APIs, follow the instructions in Setting up custom domain names for REST APIs.

For HTTP APIs, follow the instructions in Setting up custom domain names for HTTP APIs.

For WebSocket APIs, follow the instructions in Setting up custom domain names for WebSocket APIs.

Note: After a custom domain name is created in API Gateway, you must create or update your DNS provider's resource record to map to your API endpoint. For more information, see Register a domain name.

The example in this article uses a REST API Regional custom domain name setup.

Example API endpoint URLs

https://restapiId1.execute-api.us-west-2.amazonaws.com/example1/home

https://restapiId2.execute-api.us-west-2.amazonaws.com/example2/home

Example custom domain URL (without base path mapping)

https://apigw.customdomain.com/example1/home

https://apigw.customdomain.com/example2/home

Create a CloudFront web distribution

1.    Open the CloudFront console, and then choose Create Distribution.

2.    On the Select a delivery method for your content page, under Web, choose Get Started.

3.    On the Create Distribution page, for Origin Domain, paste your API's custom domain URL similar to the following example:

Origin domain name example

https://apigw.customdomain.com

4. For Origin path, leave it blank . Note: Entering an incorrect base path for origin path when invoking the CloudFront web distribution can result in an error. For example, an unauthorized request error that returns the error "Missing Authentication Token" and a 403 Forbidden response code.

5.    For Minimum Origin SSL Protocol, it's a best practice to choose TLSv1.2. Don't choose SSLv3. API Gateway doesn't support the SSLv3 protocol.

6.    For Protocol, choose HTTPS Only. Note: API Gateway doesn't support unencrypted HTTP endpoints. For more information, see Amazon API Gateway FAQs.

7.    (Optional) To forward custom headers to your origin, choose Add header, and enter your Header name and Value. Note: For a list of custom headers that CloudFront can't add, see Custom headers that CloudFront can't add to origin requests.

8.    Choose Create Distribution.

After CloudFront creates your distribution, the value of the Status column for your distribution changes from InProgress to Deployed.

For more information, see Creating a distribution.

Test your CloudFront web distribution

1.    Open the CloudFront console, copy the Domain Name of your web distribution to your clipboard similar to the following example:

Non-custom domain name example

a222222bcdefg5.cloudfront.net

2.    Follow the instructions for Testing a distribution.

A successful test returns a 200 OK response. If you get a 500 server error code, then the web distribution might not be deployed. If you get no response, the CloudFront DNS record hasn't propagated yet.

After the CloudFront distribution is created, your setup is configured as follows:

a222222bcdefg5.cloudfront.net/example1/home --> apigw.customdomain.com/example1/home --> API-1

a222222bcdefg5.cloudfront.net/example2/home --> apigw.customdomain.com/example2/home --> API-2

You are now able to make a request to two APIs from a single CloudFront distribution with your API Gateway custom domain name.

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

---

Related information

Choose an endpoint type to set up for an API Gateway API

Working with API mappings for Websocket APIs

Working with API mappings for REST APIs

Working with API mappings for HTTP APIs