Route 53 custom domains for API Gateway are surprisingly not about getting your API to a friendlier URL, but about enabling TLS termination at the edge.
Let’s see this in action. Imagine you have an API Gateway endpoint like https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/users. We want to access this via api.example.com/users.
First, we need to create a REST API in API Gateway. For this example, let’s assume we have a simple GET method on /users that returns a static JSON response.
Now, to associate a custom domain, we navigate to "Custom domain names" in the API Gateway console. We’ll enter api.example.com as the domain name. Crucially, we need an ACM (AWS Certificate Manager) certificate for this domain. If you don’t have one, you’ll need to request it. This certificate must be in the us-east-1 region, regardless of where your API Gateway is deployed, because the API Gateway custom domain is a global resource. Let’s say we have a certificate with the ARN arn:aws:acm:us-east-1:123456789012:certificate/your-certificate-id.
Once the certificate is selected, we need to configure a "path mapping." This is where we link our custom domain to the specific API and stage. We’ll create a new mapping:
- API Gateway API: Select your API (e.g., "MyUserAPI").
- Stage: Select your deployment stage (e.g., "prod").
- Path (optional): Leave this blank for a root mapping, or specify a path like
/v1if you wantapi.example.com/v1to point to this stage.
After saving, API Gateway will provision an "API Gateway domain name," which looks something like d-abcdef123.execute-api.us-east-1.amazonaws.com. This is the target for your Route 53 record.
Now, head over to Route 53. In your hosted zone for example.com, create a new record:
- Record name:
api(forapi.example.com). - Record type:
A. - Alias: Toggle this to "Yes."
- Route traffic to: Select "Alias to API Gateway API."
- Region: Select "Global."
- API Gateway API: Choose the API Gateway custom domain name you just created (e.g.,
d-abcdef123.execute-api.us-east-1.amazonaws.com).
This setup allows api.example.com to resolve to the API Gateway edge endpoint. When a request comes in for https://api.example.com/users, Route 53 directs it to the API Gateway edge, which then uses your ACM certificate to establish a TLS connection, decrypts the request, and forwards it to your actual API Gateway backend (e.g., https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/users). The key benefit here is that TLS termination happens at the edge, reducing latency and offloading SSL processing from your origin.
The most surprising part is that the "API Gateway domain name" created in API Gateway is not the same as the actual DNS name you’ll use in Route 53. It’s an intermediary endpoint that Route 53 points to, and API Gateway uses this to find your custom domain configuration. You’re essentially aliasing your friendly domain to a dynamically generated, edge-optimized endpoint that API Gateway manages.
The next thing you’ll likely run into is wanting to use different API Gateway stages or even different APIs under subdomains or paths, which involves configuring multiple path mappings and potentially multiple Route 53 alias records.