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 req will 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: APIs » Custom Domain Names.

API Gateway custom domain creation form

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 redir service.

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.

API Gateway custom domain update form

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.

Route 53 coolstory.me A record