With AWS API Gateway, you can create and manage RESTful APIs, but by default, they’re hosted on AWS’s domain (https://xyz.execute-api.region.amazonaws.com). For a more professional appearance, integrating a custom domain is essential—especially if you’re looking to improve branding and build customer trust. In this guide, I’ll walk you through the steps to set up a custom domain for API Gateway using AWS tools.
Prerequisites
- A registered domain: You can register your domain through Amazon Route 53 or any other DNS provider.
- API Gateway API: Ensure you have an API deployed to at least one stage (e.g., “prod” or “dev”).
Step 1: Set Up Your Domain in Route 53 or DNS Provider
If you’re using Route 53:
- Go to the Route 53 console.
- Create a Hosted Zone for your domain if one doesn’t already exist.
- Ensure that you have access to manage DNS records for your domain.
If you’re using an external DNS provider:
- Access your provider’s control panel, as you’ll need to add CNAME or A records later to point the custom domain to API Gateway.
Step 2: Request a Certificate in AWS Certificate Manager (ACM)
Before creating a custom domain for API Gateway, you need an SSL certificate for secure HTTPS connections.
- Go to AWS Certificate Manager (ACM) in the AWS Management Console.
- Click Request a certificate and select Request a public certificate.
- Enter the custom domain name you want to use (e.g.,
api.yourdomain.com) and submit the request. - ACM will require you to verify your ownership. To do this, you’ll be prompted to add a CNAME record to your DNS records.
- Once ACM verifies your ownership, the certificate will be issued. This may take a few minutes, but you’ll see the certificate status update to Issued in the ACM console.
Tip: Make sure to select the region where you plan to deploy your API or go with a certificate in us-east-1 for Edge-optimized endpoints.
Step 3: Create a Custom Domain in API Gateway
Now that you have a valid SSL certificate, head over to the API Gateway console.
- In the left menu, select Custom domain names and click Create.
- Enter your custom domain name (e.g.,
api.yourdomain.com). - Choose the endpoint type:
- Edge-optimized: Use this if your API is meant for global traffic, as AWS will distribute the requests across edge locations.
- Regional: Choose this if your API serves clients within a single AWS region.
- Attach the ACM certificate you created in Step 2.
- Click Create Domain Name. Once created, AWS will generate a new API Gateway domain name (something like
d-xyz1234.execute-api.region.amazonaws.com) that will route traffic to your API.
Step 4: Set Up API Mapping
API Gateway needs to know which API and stage to serve when requests hit your custom domain.
- In API Gateway, go to API Mappings under the newly created custom domain name.
- Click Configure API Mappings.
- Select your API, choose a Stage (such as
prod), and define the Base Path:- Base Path: Leave it blank if you want requests to be served from the root of your custom domain. Otherwise, you can specify a path (e.g.,
/v1), making your API accessible athttps://api.yourdomain.com/v1.
- Base Path: Leave it blank if you want requests to be served from the root of your custom domain. Otherwise, you can specify a path (e.g.,
- Save the settings, and your API will be mapped to the custom domain.
Step 5: Update DNS Settings
To make your custom domain accessible, you’ll need to create a DNS record that points your custom domain to the API Gateway domain.
- In Route 53 (or your DNS provider), create a new A record (or Alias Record in Route 53).
- Set the name to your custom domain (e.g.,
api.yourdomain.com). - In Route 53, choose Alias to API Gateway and select the API Gateway domain name generated in Step 3.
- If you’re using another DNS provider, create a CNAME record pointing to the API Gateway domain name provided by AWS.
- Set the name to your custom domain (e.g.,
Note: DNS changes can take a few minutes to propagate, but typically this should be accessible within 5–10 minutes.
Step 6: Test Your Custom Domain
Now that everything is set up, it’s time to test your new custom domain!
- In a browser or API client (like Postman), enter
https://api.yourdomain.com(or the path specified in the API mapping). - You should receive responses from your API, confirming that your custom domain configuration is successful.
Troubleshooting Tips
- 403 Forbidden: This error can occur if the endpoint type (Regional vs. Edge-optimized) in API Gateway doesn’t match your API’s region or if permissions are restricted.
- Certificate Issues: Ensure that your certificate is active in ACM and associated with the custom domain in API Gateway.
- DNS Propagation: It may take up to 24 hours for DNS changes to propagate, although it’s often much faster.
With these steps, you now have a custom domain configured for your AWS API Gateway, giving your users a seamless experience with branded URLs. This setup is a fantastic way to enhance your API’s usability, improve security with HTTPS, and boost the trustworthiness of your service!