AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

How can I set up a public custom domain name for my API Gateway API?

4 minute read

I want to use a custom domain name for my Amazon API Gateway API instead of the default base URL.

Short description

There are two types of custom domain names that you can create for API Gateway APIs: Regional or (for REST APIs only) edge-optimized.

Note: API Gateway supports custom domain names for private APIs.

To set up a custom domain name for your API Gateway API, do the following:

Request or import an SSL/TLS certificate.
Create the custom domain name for your REST API, HTTP API, or WebSocket API.
To test the configuration, use the new custom domain name to call your API.

To successfully configure a custom domain, you must understand the differences between the custom domain name types. The following are some key differences between Regional and edge-optimized custom domain names:

For target endpoints, regional custom domain names use a Regional API endpoint. Edge-optimized custom domain names use an Amazon CloudFront distribution.
For SSL/TLS certificates, regional custom domain names must use an SSL/TLS certificate that's in the same AWS Region as your API. Edge-optimized custom domain names must use a certificate that's in the following Region: US East (N. Virginia) (us-east-1).
For custom domain names, you can share regional custom domain names across different AWS Regions. Edge-optimized custom domain names are unique. You can't associate custom domain names with more than one CloudFront distribution.
For domain names, you can't map a Regional custom domain name for a WebSocket API to a REST API or HTTP API. However, you can associate a Regional custom domain with REST APIs and HTTP APIs. For REST APIs, both edge-optimized and Regional custom domain names can have mappings for edge-optimized API endpoints, Regional API endpoints, or both. For WebSocket APIs and HTTP APIs, TLS 1.2 is the only supported TLS version.

Resolution

Request or import an SSL/TLS certificate

Before you create a custom domain name for your API, you must do one of the following:

Request an SSL/TLS certificate from AWS Certificate Manager (ACM).
Import an SSL/TLS certificate into ACM.

Note: For more information, see Get certificates ready in AWS Certificate Manager.

When you request or import the certificate, you must meet the following requirements:

To pass domain validation checks, the certificate must include the custom domain name as an alternate domain name.
Note: For more information about validation checks with CloudFront distributions for edge-optimized custom domain names, see Continually Enhancing Domain Security on Amazon CloudFront. There are similar validation checks for Regional custom domain names.
For a Regional custom domain name, the ACM certificate must be in the same Region as your API.

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

For REST APIs, follow the instructions in Custom domain name for public REST APIs in API Gateway.

For HTTP APIs, follow the instructions in Custom domain names for HTTP APIs in API Gateway.

For WebSocket APIs, follow the instructions in Custom domain names for WebSocket APIs in API.

Route traffic to your API Gateway API

To route traffic to your custom domain, use Amazon Route 53.

To route traffic to your API Gateway API, follow the instructions in Configuring Route 53 to route traffic to an API Gateway endpoint.

When you configure Route 53, you must create either a public hosted zone or a private hosted zone. For internet-facing applications with resources that you want to make available to users, choose a public hosted zone. For more information, see Working with hosted zones.

To determine where traffic for your domain is routed, Route 53 uses records. Alias records provide easier DNS queries to AWS resources, while CNAME (non-alias) records can redirect DNS queries outside of AWS resources. For more information, see Choosing between alias and non-alias records.

Test the configuration

To test the configuration, you can use the new custom domain name to call the API:

Use the base path mapping that you specify when you create the custom domain name to run a curl command on the domain name.
Note: For more information about curl, see the curl project website.
Verify that the response to the custom domain name is the same response that you receive when you invoke the API stage URL.