How do I set up API Gateway with my own CloudFront distribution?

Last updated: 2019-01-11

I want an edge-optimized API endpoint in Amazon API Gateway, but I need more control over the Amazon CloudFront distribution. Can I create and use my own distribution?

Short Description

If your API clients are geographically dispersed, you might want an edge-optimized API endpoint in API Gateway. This type of endpoint acts like a regional endpoint, but has an AWS managed CloudFront web distribution in front of it to help improve the client connection time.

However, you can get the benefit of the global CloudFront content delivery network while keeping more control over the distribution. For this setup, use a regional API with a custom CloudFront distribution manually assigned in front of it.


Create a regional API in API Gateway, and then follow these instructions.

Set up a GET method for your API

  1. In the API Gateway console, choose the name of your new regional API.
  2. In the Resources pane, choose Actions, and then choose Create Method.
  3. Choose GET from the list that appears under the / resource node, and then choose the check mark icon.
  4. In / - GET - Setup, for Integration type, choose Mock, and then choose Save. A mock integration responds to any request that reaches it, which will help later with testing.

Deploy your API

  1. Choose your API in the API Gateway console.
  2. Choose Actions, and then choose Deploy API.
  3. In Deploy API, for Deployment stage, choose [New Stage].
  4. For Stage name, enter a name. For example, enter test.
  5. Choose Deploy.
  6. In the Stage Editor panel, copy the Invoke URL to your clipboard. The URL looks like this:

Test your API

Test your API's URL for a "200" HTTP status code using the API Gateway console, the Postman app, or curl from a command line interface. If you use curl, then:

In Linux, run this command:

curl -IX GET

In Windows PowerShell, run this command:


Note: In these commands, replace restapi-id, region, and stageName with the values from your API's URL.

For more information about curl, see the cURL project website.

Note: If you get a status code other than "200," be sure that you deployed the API to your stage in the console. Also, be sure that you specified the stage in the URL. For example, enter /test.

Create a CloudFront web distribution

  1. In the CloudFront console, choose Create Distribution.
  2. On the first page of the Create Distribution Wizard, in the Web section, choose Get Started.
  3. For Origin Domain Name, enter your API URL, which you copied earlier.
  4. In Origin Path, enter /[stage-name]. This is the name of the API stage that you deployed earlier, with a slash in front of it. For example, enter /test.
    Note: If you want to include the stage name in the URL, don't enter anything in Origin Path.
  5. For Origin Protocol Policy, choose HTTPS Only.
    Note: API Gateway does not support unencrypted (HTTP) endpoints. For more information, see Amazon API Gateway FAQs.
  6. (Optional) To forward custom headers to your origin, enter one or more custom headers for Origin Custom Headers.
    Note: There are several custom headers that CloudFront can't forward to your origin.
  7. (Optional) To use your own custom domain names for the distribution instead of the one CloudFront assigns to it, enter one or more domain names for Alternate Domain Names (CNAMEs). For more information, see Using Custom URLs for Files by Adding Alternate Domain Names (CNAMEs).
  8. (Optional) Configure any additional settings that you want to customize, such as Origin SSL Protocols.
    Note: For Origin SSL Protocols, be sure that you don't choose SSLv3, because API Gateway doesn't support that protocol. It's a best practice to choose TLSv1.2 only.
    Important: Be careful about changing the setting Cache Based on Selected Request Headers under Default Cache Behavior Settings. If you change this setting to All, or if you change this setting to Whitelist and then add the Host header to the whitelist, then your setup won't work. For more information, see Caching Content Based on Request Headers.
  9. Choose Create Distribution.
  10. Wait for your distribution to deploy. This might take about 30 minutes. When its Status appears as Deployed in the console, the distribution is ready.

Test your CloudFront web distribution

  1. In the CloudFront console, note the Domain Name of your distribution. If you didn't use a custom domain name, the domain looks like this:
  2. Test the domain name for a "200" HTTP status code using one of the methods mentioned above in step 6 of Deploy and test your API.
    Note: If you get a "500" server error code, the distribution might not be fully deployed. If you get no response, the CloudFront DNS record might not have fully propagated yet. In either case, wait 20 minutes, and then retry the procedure.

Your API now uses the distribution that you created, and you can access any resources on the API using the CloudFront URL.