Introduction

You do not normally point a custom domain at API Gateway by guessing the endpoint hostname and creating a raw DNS record only. The usual workflow is to create a custom domain in API Gateway, attach an ACM certificate, map it to your API stage, and then point DNS at the target AWS gives you.

The exact DNS record depends on the kind of hostname you are publishing. For a subdomain such as api.example.com, a CNAME can work in many DNS providers. For an apex domain such as example.com, you usually need an alias-style record such as Route 53 alias, ALIAS, or ANAME rather than a standard CNAME.

Start in API Gateway, Not in DNS

First create a custom domain name in API Gateway and attach the certificate for that hostname. Then create the API mapping to your stage.

The AWS-side flow is:

1. create the custom domain
2. attach the ACM certificate
3. add the API mapping
4. note the target domain name AWS provides

That target is the value your DNS record should point to. Without the API Gateway custom-domain setup, DNS alone does not give the service enough information to serve your hostname correctly.

Example DNS Strategy

If your custom hostname is api.example.com, a DNS record can look like this conceptually:

api.example.com.  CNAME  d-abc123.execute-api.us-east-1.amazonaws.com.

But if you use Route 53, the better AWS-native setup is often an alias record pointing at the API Gateway target rather than a plain CNAME, because alias records integrate better with AWS service endpoints and can be used at the zone apex.

So the practical rule is:

• subdomain with non-Route-53 DNS: often CNAME
• subdomain with Route 53: alias is usually preferable
• apex domain: standard CNAME is not allowed, so use alias-style DNS if your provider supports it

Regional Versus Edge-Optimized Domains

API Gateway custom domains can be regional or edge-optimized. That affects what target AWS gives you and which certificate region rules apply.

In general terms:

• regional custom domains stay tied to a specific AWS region
• edge-optimized custom domains sit behind CloudFront distribution behavior

The DNS step still follows the same pattern: point your record at the AWS-provided target for that custom domain. The difference is which target AWS gives you and how traffic is routed behind the scenes.

Verify the Mapping End to End

After creating the record, confirm all three layers:

• the API Gateway custom domain is in an available state
• the API mapping points to the intended API and stage
• DNS resolves to the expected AWS target

Command-line checks are useful here:

dig api.example.com
nslookup api.example.com

Those commands confirm DNS resolution, but they do not guarantee the API mapping is correct. For that, test the actual HTTPS request too.

Why People Get Stuck

The most common failure mode is trying to skip the custom-domain setup and only adding DNS. Another is creating a CNAME at the root domain, which standard DNS does not permit.

A third common problem is certificate mismatch. Even if DNS is correct, the TLS certificate must cover the custom hostname and must be attached in the place API Gateway expects.

Common Pitfalls

• Creating DNS records before creating the API Gateway custom domain and API mapping.
• Trying to use a standard CNAME at the zone apex.
• Pointing DNS at the wrong AWS hostname instead of the one API Gateway generated for the custom domain.
• Forgetting that the certificate must match the custom hostname.
• Validating only DNS resolution and not the actual HTTPS request path through API Gateway.

Summary

• The normal flow is API Gateway custom domain first, DNS second.
• A CNAME can work for a subdomain, but apex domains usually need alias-style DNS.
• Use the exact target hostname AWS gives you for the custom domain.
• Confirm certificate, API mapping, and DNS together.
• If you are using Route 53, alias records are often the cleaner AWS-native choice.