How to use custom domain API Gateway

AwsHow-ToBeginner · 4 min read

How to Use Custom Domain with AWS API Gateway

To use a custom domain with AWS API Gateway, first create a custom domain name in API Gateway and associate it with an SSL/TLS certificate from AWS Certificate Manager (ACM). Then, map your API stages to this domain and update your DNS records to point your domain to the API Gateway endpoint.

📐

Syntax

Setting up a custom domain in AWS API Gateway involves these key parts:

Custom Domain Name: Your own domain like api.example.com.
ACM Certificate: A valid SSL/TLS certificate for your domain managed by AWS Certificate Manager.
Base Path Mapping: Links your API stages to paths on your custom domain.
DNS Record: A record in your DNS provider pointing your domain to the API Gateway endpoint.

bash

aws apigateway create-domain-name --domain-name api.example.com --certificate-arn arn:aws:acm:region:account:certificate/certificate-id

aws apigateway create-base-path-mapping --domain-name api.example.com --rest-api-id your-api-id --stage prod

# Update DNS with a CNAME or Alias record pointing to the domain name's target domain name

💻

Example

This example shows how to create a custom domain, map an API stage, and update DNS using AWS CLI commands.

bash

aws apigateway create-domain-name \
  --domain-name api.example.com \
  --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-5678-90ef-ghij-klmnopqrstuv

aws apigateway create-base-path-mapping \
  --domain-name api.example.com \
  --rest-api-id a1b2c3d4e5 \
  --stage prod

# After this, go to your DNS provider and create a CNAME record:
# Name: api.example.com
# Value: d-abcdefghij.execute-api.us-east-1.amazonaws.com

# This points your custom domain to the API Gateway endpoint.

Output

Domain name 'api.example.com' created with certificate arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-5678-90ef-ghij-klmnopqrstuv Base path mapping created for domain 'api.example.com' to API 'a1b2c3d4e5' stage 'prod' DNS record updated at your DNS provider

⚠️

Common Pitfalls

Missing or invalid ACM certificate: The certificate must be in the same AWS region as your API Gateway (usually us-east-1 for edge-optimized).
Incorrect DNS record: Using the wrong DNS type or value will cause your domain not to resolve.
Not mapping base path: Without base path mapping, your API won't respond on the custom domain.
Propagation delay: DNS changes can take time to propagate; be patient before testing.

bash

## Wrong way: Using a certificate from a different region
aws apigateway create-domain-name --domain-name api.example.com --certificate-arn arn:aws:acm:us-west-2:123456789012:certificate/abcd1234

## Right way: Use certificate in us-east-1 for edge-optimized APIs
aws apigateway create-domain-name --domain-name api.example.com --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/abcd1234

📊

Quick Reference

Remember these steps to use a custom domain with API Gateway:

Request or import an SSL certificate in AWS Certificate Manager.
Create a custom domain name in API Gateway linked to the certificate.
Map your API stage to the custom domain using base path mapping.
Update your DNS provider with a CNAME or Alias record pointing to the API Gateway domain.
Wait for DNS propagation before testing your API on the custom domain.

✅

Key Takeaways

Always use an ACM certificate in the correct AWS region for your custom domain.

Map your API stages to the custom domain with base path mappings to route traffic correctly.

Update your DNS records to point your domain to the API Gateway endpoint for accessibility.

Allow time for DNS changes to propagate before testing your custom domain.

Check for common errors like wrong certificate region or missing base path mappings.