Set up an edge-optimized custom domain name in API Gateway - Amazon API Gateway
ConsiderationsCreate an edge-optimize custom domain nameCreate a DNS record for your edge-optimized custom domain nameConfigure base path mapping of an API with a custom domain name as its hostnameRotate a certificate imported into ACMCall your API with custom domain names
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Set up an edge-optimized custom domain name in API Gateway

When you create a custom domain name for an edge-optimized API, API Gateway sets up a CloudFront distribution and a DNS record to map the API domain name to the CloudFront distribution domain name. Requests for the API are then routed to API Gateway through the mapped CloudFront distribution. This mapping is for API requests that are bound for the custom domain name to be routed to API Gateway through the mapped CloudFront distribution.

Considerations

The following are considerations for your edge-optimized custom domain name.

  • To set up an edge-optimized custom domain name or to update its certificate, you must have a permission to update CloudFront distributions.

    The following permissions are required to update CloudFront distributions: 

    {
    "Version": "2012-10-17",
    "Statement": [
         {
            "Sid": "AllowCloudFrontUpdateDistribution",
            "Effect": "Allow",
            "Action": [
                "cloudfront:updateDistribution"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

  • You must request or import a certificate for your edge-optimized custom domain name in the US East (N. Virginia) – us-east-1 Region.

  • API Gateway supports edge-optimized custom domain names by leveraging Server Name Indication (SNI) on the CloudFront distribution. For more information on using custom domain names on a CloudFront distribution, including the required certificate format and the maximum size of a certificate key length, see Using Alternate Domain Names and HTTPS in the Amazon CloudFront Developer Guide

  • An edge-optimized custom domain names takes about 40 minutes to be ready.

  • After you create your edge-optimized custom domain name, you must create a DNS record to map the custom domain name to the CloudFront distribution name.

Create an edge-optimize custom domain name

The following procedure describes how to create an edge-optimized custom domain name for an API.

Amazon Web Services Management Console

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. Choose Custom domain names from the main navigation pane.

  3. Choose Create.

  4. For Domain name, enter a domain name.

  5. For Minimum TLS version, select a version.

  6. Under Endpoint configuration, for API endpoint type, choose Edge-optimized.

  7. For ACM certificate, choose an ACM certificate.

  8. Choose Create domain name.

REST API

  1. Call domainname:create, specifying the custom domain name and the ARN of a certificate stored in Amazon Certificate Manager.

    The successful API call returns a 201 Created response containing the certificate ARN as well as the associated CloudFront distribution name in its payload.

  2. Note the CloudFront distribution domain name shown in the output. You need it in the next step to set the custom domain's CNAME value or A-record alias target in your DNS.

For code examples of this REST API call, see domainname:create.

An edge-optimized custom domain names takes about 40 minutes to be ready, but the console immediately displays the associated CloudFront distribution domain name, in the form of distribution-id.cloudfront.net, along with the certificate ARN. In the meantime, you can continue to the next step and configure the DNS record alias to map the custom domain name to the associated CloudFront distribution domain name.

Create a DNS record for your edge-optimized custom domain name

After you initiate the creation of your edge-optimized custom domain name, set up the DNS record alias.

We recommend that you use Route 53 to create an A-record alias for your custom domain name and specify the CloudFront distribution domain name as the alias target. This means that Route 53 can route your custom domain name even if it is a zone apex. For more information, see Choosing Between Alias and Non-Alias Resource Record Sets in the Amazon Route 53 Developer Guide.

You can instead add your custom domain to the hosted zone as a CNAME resource record set. The CNAME record name specifies the custom domain name you entered earlier in Domain Name (for example, api.example.com). The CNAME record value specifies the domain name for the CloudFront distribution.

However, use of a CNAME record will not work if your custom domain is a zone apex (i.e., example.com instead of api.example.com). A zone apex is also commonly known as the root domain of your organization. For a zone apex you need to use an A-record alias, provided that is supported by your DNS provider.

For instructions for Amazon Route 53, see Routing traffic to an Amazon API Gateway API by using your domain name in the Amazon Route 53 Developer Guide.

Configure base path mapping of an API with a custom domain name as its hostname

You can use base path mapping to use a single custom domain name as the hostname of multiple APIs. This makes an API accessible through the combination of the custom domain name and the associated base path.

For example, if in API Gateway, you created an API named PetStore and another API named Dogs and then set up a custom domain name of api.example.com, you can set the PetStore API's URL as https://api.example.com.

This associates the PetStore API with the base path of an empty string. If you set the PetStore API's URL as https://api.example.com/PetStore, this associates the PetStore API with the base path of PetStore. You can assign a base path of MyDogList for the Dogs API. The URL of https://api.example.com/MyDogList is then the root URL of the Dogs API.

To configure API mappings on multiple levels, you can only use a Regional custom domain name. Edge-optimized custom domain names are not supported. For more information, see Map API stages to a custom domain name.

The following procedure sets up API mappings to map paths from your custom domain name to your API stages.

Amazon Web Services Management Console

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. Choose Custom domain names from the API Gateway console main navigation pane.

  3. Choose a custom domain name.

  4. Choose Configure API mappings.

  5. Choose Add new mapping.

  6. Specify the API, Stage, and Path (optional) for the mapping.

  7. Choose Save.

REST API

Call basepathmapping:create on a specific custom domain name, specifying the basePath, restApiId, and a deployment stage property in the request payload.

The successful API call returns a 201 Created response.

For code examples of the REST API call, see basepathmapping:create.

Rotate a certificate imported into ACM

ACM automatically handles renewal of certificates it issues. You do not need to rotate any ACM-issued certificates for your custom domain names. CloudFront handles it on your behalf.

However, if you import a certificate into ACM and use it for a custom domain name, you must rotate the certificate before it expires. This involves importing a new third-party certificate for the domain name and rotate the existing certificate to the new one. You need to repeat the process when the newly imported certificate expires. Alternatively, you can request ACM to issue a new certificate for the domain name and rotate the existing one to the new ACM-issued certificate. After that, you can leave ACM and CloudFront to handle the certificate rotation for you automatically. To create or import a new ACM certificate, follow the steps in To create or import an SSL/TLS certificate into ACM.

The following procedure describes how to rotate a certificate for a domain name.

Note

It takes about 40 minutes to rotate a certificate imported into ACM.

Amazon Web Services Management Console

  1. Request or import a certificate in ACM.

  2. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  3. Choose Custom domain names from the API Gateway console main navigation pane.

  4. Choose a custom domain name.

  5. Choose Edit.

  6. Choose the desired certificate from the ACM certificate dropdown list.

  7. Choose Save to begin rotating the certificate for the custom domain name.

  8. After the rotation is done, you can choose the two-way arrow icon next to ACM Certificate to roll back to the original certificate.

REST API

Call domainname:update action, specifying the ARN of the new ACM certificate for the specified domain name.

Call your API with custom domain names

Calling an API with a custom domain name is the same as calling the API with its default domain name, provided that the correct URL is used.

The following examples compare and contrast a set of default URLs and corresponding custom URLs of two APIs (udxjef and qf3duz) in a specified Region (us-east-1), and of a given custom domain name (api.example.com).

Root URLs of APIs with default and custom domain names
API ID Stage Default URL Base path Custom URL
udxjef prod https://udxjef.execute-api.us-east-1.amazonaws.com/prod /petstore https://api.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://api.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://api.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

API Gateway supports custom domain names for an API by using Server Name Indication (SNI). You can invoke the API with a custom domain name using a browser or a client library that supports SNI.

API Gateway enforces SNI on the CloudFront distribution. For information on how CloudFront uses custom domain names, see Amazon CloudFront Custom SSL.