How do I define a custom domain name for my API Gateway API?
Last updated: 2020-05-22
I want to use a custom domain name for my Amazon API Gateway API instead of using the default base URL. How do I set that up?
|Custom domain name type||API type||Target endpoint||SSL/TLS certificate||Domain name|
|Edge-optimized||Only REST APIs can use edge-optimized custom domain names.||An Amazon CloudFront distribution with a format similar to examplek7xoo.cloudfront.net.||The certificate must be in the US East (N. Virginia) (us-east-1) AWS Region.||The domain name must be unique. (It's attached to a CloudFront distribution endpoint as a CNAME, and you can't associate a CNAME with more than one CloudFront distribution.)|
|Regional||All these API types can use Regional custom domain names:
|A Regional API endpoint with a format similar to examplevpz7.execute-api.us-west-2.amazonaws.com.||The certificate must be in the same Region as your API.||The domain name can be shared by other Regional custom domain names in different Regions.|
Also, note these key differences for domain name mapping:
- For REST APIs, both edge-optimized and Regional custom domain names can have mappings for edge-optimized API endpoints, Regional API endpoints, or both.
Note: Custom domain names aren't supported for private REST APIs.
- For WebSocket APIs and HTTP APIs, TLS 1.2 is the only supported TLS version.
- 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.
Request or import an SSL/TLS certificate
Before creating a custom domain name for your API, you must request an SSL/TLS certificate from AWS Certificate Manager (ACM), or import an SSL/TLS certificate into ACM. For more information, see Getting certificates ready in AWS Certificate Manager.
When requesting or importing the certificate, note the following requirements:
- To pass domain validation checks, the certificate must include the custom domain name as an alternate domain name. 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 US East (N. Virginia) (us-east-1) Region.
- For a Regional custom domain name, the ACM certificate must be in the same Region as your API.
Create the custom domain name
Depending on your API Gateway API type, choose from the following for instructions to create a custom domain name:
- Setting up custom domain names for REST APIs
- Setting up custom domain names for WebSocket APIs
- Setting up custom domain names for HTTP APIs
Test the custom domain name
- 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.
- Verify that the response to the custom domain name is the same response that you receive when you invoke the API stage URL.