Using custom domains with Amazon's API Gateway
Let's work together!
Are you hiring for remote engineering leadership positions? I help teams thrive through iterative improvement. Here's my resume. Let's talk.
I'm also available for DevOps project work. Are you fighting fires instead of serving your customers? Hire me to identify the roadblocks and make improvements so you can get back to focusing on your customers.
In my last post Build a serverless URL shortener with AWS Lambda and API Gateway services I walked through creating a URL shortener service using Amazon’s API Gateway and Lambda services. One of my goals for that project was to use a custom domain instead of the randomized URL provided by API Gateway. This turned out to be trickier than I expected.
API Gateway supports custom domains but it requires an SSL certificate. And there are no integrations with Route 53 or the new AWS Certificate Manager. You’ll need to do a few things by hand to get started. Amazon’s docs on the subject are thorough. The following is what I did to get coolstory.me working with my URL shortener service.
SSL Certificate Required
You can’t get started adding a custom domain to an API Gateway service without a valid SSL certificate for the domain you want to use. If you’re experimenting with API Gateway and hesitant to commit to purchasing a certificate consider using a free provider such as Let’s Encrypt or StartSSL.
I created a free certificate with StartSSL. If you’re familiar with generating SSL certificates you can skip this next part. If not you’ll need to do a few things:
- Have a custom domain registered and resolvable.
- Validate ownership of your domain with your provider of choice. StartSSL provides a wizard to do this.
- Generate a private key and certificate signing request using openssl on your computer:
> mkdir coolstory-ssl > cd coolstory-ssl > openssl genrsa -out coolstory.me.key 2048 > openssl req -new -sha256 -key coolstory.me.key -out coolstory.me.csr
openssl reqwill ask a series of questions. The most important one is the domain you want to use. Make sure to use exactly the domain you will use.
- Submit a request for a new certificate with your provider of choice. StartSSL provides a web wizard for this step as well. You will need the CSR file you generated to do this.
Once you have the certificate you can add the custom domain under the API Gateway web panel. You’ll need the private key you generated and used to create the CSR. Create a new custom domain under the API Gateway tabs:
Custom Domain Names.
Pointing Your Domain at an API Gateway Service
Once you create the custom domain name entry with API Gateway you will need to map it to an API stage. The example below shows how
coolstory.me maps to the
/v1 endpoint of my
The example also shows a CloudFront distribution domain name. This is domain is different than the invocation URL API Gateway gives you when you deploy a service stage. You can map a CNAME from you domain to this CloudFront domain.
Using an Apex Domain
Since this project is a URL shortener I wanted to use an apex domain
coolstory.me not a longer subdomain like
links.coolstory.me. Route 53 supports pointing apex domain records at internal service aliases. This works with API Gateway custom domain CloudFront distribution domains.
Since I have my domain DNS zone hosted with Route 53 I was able to create a link to the CloudFront distribution domain for the A record.
February 26, 2016