AWS API Gateway custom domains allow you to create a branded, user-friendly URL for your APIs instead of using the default API Gateway endpoint. By default, when you create an API in API Gateway, you receive an endpoint like https://api-id.execute-api.region.amazonaws.com/stage. Custom domains enab…AWS API Gateway custom domains allow you to create a branded, user-friendly URL for your APIs instead of using the default API Gateway endpoint. By default, when you create an API in API Gateway, you receive an endpoint like https://api-id.execute-api.region.amazonaws.com/stage. Custom domains enable you to use your own domain name, such as api.yourcompany.com, providing a more professional and memorable experience for API consumers.
To set up a custom domain, you first need an SSL/TLS certificate in AWS Certificate Manager (ACM). For Regional endpoints, the certificate must be in the same region as your API. For Edge-optimized endpoints, the certificate must be in us-east-1. The certificate validates ownership of your domain.
API Gateway supports two endpoint types for custom domains: Edge-optimized (distributed via CloudFront) and Regional. Edge-optimized endpoints are ideal for geographically distributed clients, while Regional endpoints work better when clients are in the same region.
Base path mappings connect your custom domain to specific API stages. You can map multiple APIs and stages to a single custom domain using different base paths. For example, api.yourcompany.com/v1 could point to version 1, while api.yourcompany.com/v2 points to version 2.
After creating the custom domain in API Gateway, you must configure DNS. For Edge-optimized domains, create a CNAME or A-record alias pointing to the CloudFront distribution. For Regional endpoints, point to the Regional domain name provided by API Gateway.
Mutual TLS (mTLS) authentication can be enabled on custom domains for enhanced security, requiring clients to present certificates during the TLS handshake.
Custom domains also support domain name ownership verification and allow you to maintain consistent API URLs even when underlying APIs change, enabling seamless versioning and migration strategies for your applications.
API Gateway Custom Domains
What Are API Gateway Custom Domains?
API Gateway custom domains allow you to use your own domain name (like api.yourcompany.com) instead of the default AWS-generated endpoint (like abc123.execute-api.us-east-1.amazonaws.com). This provides a professional, branded API endpoint for your consumers.
Why Are Custom Domains Important?
• Branding: Present a professional appearance with your own domain name • Consistency: Maintain the same endpoint URL even when recreating or updating APIs • Security: Use your own SSL/TLS certificates through AWS Certificate Manager (ACM) • Flexibility: Map multiple API stages to different base paths under one domain • Migration: Easier to migrate APIs between environments while keeping the same URL
How Custom Domains Work
1. Certificate Requirement: You must have an SSL/TLS certificate in AWS Certificate Manager (ACM). For edge-optimized endpoints, the certificate must be in us-east-1. For regional endpoints, the certificate must be in the same region as your API.
2. Domain Configuration: Create a custom domain name in API Gateway and associate it with your ACM certificate.
3. Base Path Mapping: Map your API stages to base paths. For example: - api.example.com/v1 → Production stage - api.example.com/v2 → New version stage
4. DNS Configuration: Create a DNS record (CNAME or A-Alias) pointing your custom domain to the API Gateway distribution domain name.
Endpoint Types and Their Differences
• Edge-Optimized: Uses CloudFront distribution. Certificate must be in us-east-1. Best for geographically distributed clients.
• Regional: No CloudFront involvement. Certificate must be in the same region. Best for clients in a single region or when using your own CDN.
• Private: Only accessible from within a VPC. Does not support custom domain names through the standard method.
Key Components
• ACM Certificate: Required for HTTPS - must be publicly trusted • Base Path Mappings: Connect API stages to URL paths • Route 53 or DNS Provider: Needed to point your domain to API Gateway • API Gateway Domain Name: The target for your DNS record
Exam Tips: Answering Questions on API Gateway Custom Domains
1. Certificate Location is Critical: When you see edge-optimized endpoint questions, remember the certificate MUST be in us-east-1. For regional endpoints, the certificate must match the API's region.
2. Route 53 Integration: Look for answers involving A-record with Alias when Route 53 is mentioned. CNAME records also work but Alias is preferred for AWS resources.
3. Base Path Mapping Scenarios: If a question asks about hosting multiple API versions under one domain, base path mapping is the solution.
4. Migration Questions: Custom domains enable zero-downtime migrations because you can swap the underlying API while keeping the same URL.
5. Private APIs: Remember that private APIs (VPC-only) do not support custom domain names in the traditional sense.
6. Common Pitfall: Questions may try to confuse you about certificate regions. Always verify whether the scenario describes edge-optimized or regional endpoints before selecting certificate region.
7. TLS Version: API Gateway custom domains support TLS 1.2. Questions about security protocols should consider this.
8. Mutual TLS (mTLS): Custom domains can be configured with mutual TLS for additional client authentication using certificates.