Set up an edge-optimized custom domain name in API Gateway - Amazon API Gateway
ConsiderationsCreate an edge-optimize custom domain nameConfigure base path mapping of an API with a custom domain name as its hostnameCreate a DNS record for your edge-optimized custom domain nameRotate a certificate imported into ACMCall your API with custom domain names when you use a base path mapping
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 Add domain name.

  4. For Domain name, enter a domain name.

  5. For Routing mode, choose API_MAPPING_ONLY.

  6. For API endpoint type, choose Edge-optimized.

  7. Choose a minimum TLS version.

  8. Choose an ACM certificate.

  9. Choose Add 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 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 create a base path mapping or a routing rule and then configure the DNS record alias to map the custom domain name to the associated CloudFront distribution domain name.

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

Because you set the routing mode to API_MAPPING_ONLY, 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 Use API mappings to connect API stages to a custom domain name for REST APIs.

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.

For more flexibility on how you route traffic to your APIs, you can change the routing mode to ROUTING_RULE_ONLY or ROUTING_RULE_THEN_API_MAPPING and create a routing rule. For more information, see Send traffic to your APIs through your custom domain name in API Gateway.

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.

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.

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 an edge-optimized custom domain name.

  5. For Endpoint configuration, choose Edit.

  6. For ACM certificate, select a certificate from dropdown list.

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

REST API

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

Amazon CLI

The following update-domain-name updates the ACM certificate for an edge-optimized domain name.

aws apigateway update-domain-name \
    --domain-name edge.example.com \
    --patch-operations "op='replace',path='/certificateArn',value='arn:aws-cn:acm:us-west-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"

The following update-domain-name updates the ACM certificate for a Regional domain name.

aws apigateway update-domain-name \
    --domain-name regional.example.com \
    --patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws-cn:acm:us-west-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"

Call your API with custom domain names when you use a base path mapping

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).

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

For more flexibility on how you route traffic to your APIs, you can create a routing rule. For more information, see Send traffic to your APIs through your custom domain name in API Gateway.

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.