Menu
Amazon API Gateway
Developer Guide

How to Create an Edge-Optimized Custom Domain Name

Set Up an Edge-Optimized Custom Domain Name for an API Gateway API

The following procedure describes how to set up a custom domain name for an API using the API Gateway console.

To set up a custom domain name using the API Gateway console

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. Choose Custom Domain Names from the main navigation pane.

  3. Choose Create Custom Domain Name next.

    1. Under New Custom Domain Name, type your domain name (for example, api.example.com) in Domain Name.

      Note

      Do not use the wildcard character (i.e., *) for your custom domain names. API Gateway does not support it, even though the API Gateway console (or the AWS CLI) accepts it and can map it to a CloudFront distribution. However, you can use wildcard certificates.

    2. Choose a certificate from the ACM Certificate list.

    3. Choose Add mapping under Base Path Mappings to set a base path (Path) for a deployed API in a given stage (selected from the Destination dropdown lists.) You can also set the base path mapping after the custom domain name is created. For more information, see Configure Base Path Mapping of an API with a Custom Domain Name as its Host Name.

    4. Choose Save.

  4. After the custom domain name is created, the console displays the associated CloudFront distribution domain name, in the form of distribution-id.cloudfront.net, along with the certificate ARN. 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.

    Note

    The newly created custom domain name takes about 40 minutes to be ready. In the meantime, you can configure the DNS record alias to map the custom domain name to the associated CloudFront distribution domain name and to set up the base path mapping for the custom domain name while the custom domain name is being initialized.

  5. In this step, we use Amazon Route 53 as an example DNS provider to show how to set up an A-record alias for your Internet domain to map the custom domain name to the associated CloudFront distribution name. The instructions can be adapted to other DNS providers.

    1. Sign in to the Amazon Route 53 console.

    2. Create an A-IPv4 address record set for your custom domain (e.g., api.example.com). An A-record maps a custom domain name to an IP4 address.

    3. Choose Yes for Alias, type the CloudFront domain name (e.g., d3boq9ikothtgw.cloudfront.net) in Alias Target, and then choose Create. The A-record alias here maps your custom domain name to the specified CloudFront domain name that is itself mapped to an IP4 address.

      
                                Set a DNS record alias for a custom domain name for an API
                                    in API Gateway

    Tip

    The Alias Hosted Zone ID identifies the hosted zone of the specified Alias Target. The Amazon Route 53 console automatically fills in the value when you enter a valid domain name for Alias Target. To create an A-record alias without using the Amazon Route 53 console, such as when you use the AWS CLI, you must specified the required hosted zone Id. For any CloudFront distribution domain name, the hosted zone Id value is always Z2FDTNDATAQYW2, as documented in AWS Regions and Endpoints for CloudFront.

    For most DNS providers, a custom domain name is added to the hosted zone as a CNAME resource record set. The CNAME record name specifies the custom domain name you typed 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.

    With Amazon Route 53 you can create an A record alias for your custom domain name and specify the CloudFront distribution domain name as the alias target, as shown above. This means that Amazon 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.

    Use of A-record aliases also eliminates exposure of the underlying CloudFront distribution domain name because the domain name mapping takes place solely within Amazon Route 53. For these reasons, we recommend that you use Amazon Route 53 A-record alias whenever possible.

In addition to using the API Gateway console, you can use the API Gateway REST API, AWS CLI or one of the AWS SDKs to set up the custom domain name for your APIs. As an illustration, the following procedure outlines the steps to do so using the REST API calls.

To set up a custom domain name using the API Gateway REST API

  1. Call domainname:create, specifying the custom domain name and the ARN of a certificate stored in AWS 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.

  3. Follow Step 6 of the previous procedure to set up an A-record alias to map the custom domain name to its CloudFront distribution name.

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

Log Custom Domain Name Creation in CloudTrail

When CloudTrail is enabled for logging API Gateway calls made by your account, API Gateway logs the associated CloudFront distribution updates when a custom domain name is created or updated for an API. Because these CloudFront distributions are owned by API Gateway, each of these reported CloudFront distributions is identified by one of the following region-specific API Gateway account IDs, instead of the API owner's account ID.

Region-specific API Gateway account IDs of CloudFront distributions associated with a custom domain name

Region Account ID
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
eu-west-1 631144002099
eu-west-2 544388816663
eu-central-1 474240146802
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-southeast-1 195145609632
ap-southeast-2 798376113853

Configure Base Path Mapping of an API with a Custom Domain Name as its Host Name

You can use a single custom domain name as the host name of multiple APIs. You achieve this by configuring the base path mappings on the custom domain name. With the base path mappings, an API under the custom domain is accessible through the combination of the custom domain name and the associated base path.

For example, if you created an API named PetStore and another API named PetShop and set up a custom domain name of api.example.com in API Gateway, you can set the PetStore API's URL as https://api.example.com or https://api.example.com/myPetStore. The PetStore API is associated with the base path of an empty string or myStore under the custom domain name of api.example.com. Similarly, you can assign a base path of yourPetStore for the PetShop API. The URL of https://api.example.com/yourPetStore is then the root URL of the PetShop API.

Before setting the base path for an API, complete the steps in Set Up an Edge-Optimized Custom Domain Name for an API Gateway API.

To set the base path for API mappings using the API Gateway console

  1. Choose a custom domain name from the list of available Custom Domain Names list under your account.

  2. Choose Show Base Path Mappings or Edit.

  3. Choose Add mapping.

  4. (Optional) Type a base path name for Path, choose an API from Destination, and then choose a stage.

    Note

    The Destination list shows the deployed APIs under your account.

  5. Choose Save to finish setting up the base path mapping for the API.

Note

To delete a mapping after you create it, next to the mapping that you want to delete, choose the trash icon.

In addition, you can call the API Gateway REST API, AWS CLI, or one of the AWS SDKs to set up the base path mapping of an API with a custom domain name as its host name. As an illustration, the following procedure outlines the steps to do so using the REST API calls.

To set up the base path mapping of an API using the API Gateway 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 to request or import a new ACM Certificate for the specified domain name.

To rotate a certificate for a domain name, you can use the API Gateway console, the API Gateway REST API, AWS CLI, or one of the AWS SDKs.

To rotate an expiring certificate imported into ACM using the API Gateway console

  1. Request or import a certificate in ACM.

  2. Go back to the API Gateway console.

  3. Choose Custom Domain Names from the API Gateway console main navigation pane.

  4. Select the custom domain name of your choice, under the Custom Domain Names pane.

  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.

    Note

    It takes about 40 minutes for the process to finish. After the rotation is done, you can choose the two-way arrow icon next to ACM Certificate to roll back to the original certificate.

To illustrate how to programmatically rotate an imported certificate for a custom domain name, we outline the steps using the API Gateway REST API.

Rotate an imported certificate using the API Gateway 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 pro https://udxjef.execute-api.us-east-1.amazonaws.com/pro /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.