How do I define a custom domain name for my API Gateway API?

Last updated: 2021-05-28

I want to use a custom domain name for my Amazon API Gateway API instead of the default base URL. How do I set that up?

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: Custom domain names aren't supported for private APIs.

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

The following are some key differences between Regional and edge-optimized custom domain names.

Target endpoint differences

Regional custom domain names use a Regional API endpoint.

Edge-optimized custom domain names use an Amazon CloudFront distribution.

SSL/TLS certificate differences

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

Custom domain name differences

Regional custom domain names can be shared by other Regional custom domain names that are in different AWS Regions.

Edge-optimized custom domain names are unique and can't be associated with more than one CloudFront distribution.

Domain name mapping differences

A Regional custom domain name for a WebSocket API can't be mapped to a REST API or HTTP API. However, a Regional custom domain can be associated 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 creating a custom domain name for your API, you must do one of the following:
Request an SSL/TLS certificate from AWS Certificate Manager (ACM).
-or-
Import an SSL/TLS certificate into ACM.

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

When requesting or importing the certificate, keep in mind 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 an edge-optimized custom domain name, the ACM certificate must be in the following Region: US East (N. Virginia) (us-east-1).
  • 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 Setting up custom domain names for REST APIs.

For HTTP APIs, follow the instructions in Setting up custom domain names for HTTP APIs.

For WebSocket APIs, follow the instructions in Setting up custom domain names for WebSocket APIs.

Test the setup by calling your API using the new custom domain name

1. Run a curl command on the domain name using the base path mapping that you specified when you created the custom domain name.
Note: For more information about curl, see the curl project website.

2. Verify that the response to the custom domain name is the same response that you receive when you invoke the API stage URL.


Did this article help?


Do you need billing or technical support?