Custom Domains for AWS API Gateway Without Route 53

There’s some very good articles on using the Serverless Framework to setup custom domains for API Gateway endpoints. For my use case I wasn’t planning to use Route 53 for DNS hosting for the domain so they were missing a crucial step. This post documents that step.

Configuration

Follow the article linked above to setup the plugin and basic configuration. The configuration for the custom domain in theserverless.yml file is almost exactly as shown in the article with the exception of the createRoute53Record line which I changed to turn off the Route 53 DNS interaction.

  customDomain:
    domainName: api.example.com
    basePath: app
    createRoute53Record: false

Setup Steps

With that change the steps required to do the setup are the same as shown in the article but there is one final step required. Here’s the process.

Run the create_domain command

This one was one of the things that confused me since I didn’t want to create a new DNS entry in Route 53. This command does not create a domain since we’ve disabled the Route 53 integration. We do still need to run it because it sets up an AWS CloudFront distribution to front the API Gateway Endpoint. This takes time, up to 40 minutes according to the command output.

sls create_domain

Run a standard deploy

After the standard deploy the output will show the custom domain and, most importantly the Distribution Domain Name. That is the DNS name of the CloudFront endpoint that is pointing to the API Gateway deployment. That’s the information you’ll need to user in your DNS.

sls deploy

... // other output here

Serverless Domain Manager Summary
Domain Name
  api.example.com
Distribution Domain Name
  a2fcnefljuq1t1.cloudfront.net

Update Your DNS – Missing Step

Now you have all the information you need to setup the DNS entry to have the custom domain resolve to CloudFront and eventually the API Gateway Endpoint. Using whatever DNS configuration tool you use for your domain, add the Distribution Domain Name shown in the output of the deploy command as an ALIAS record for the custom domain. In the example shown above that would be Hostname api.example.com Alias a2fcnefljuq1t1.cloudfront.net. Note that not all DNS hosting services support ALIAS records so if you don’t see it your provider might not support it.

Check That it Worked

Now use a client like Postman or other to hit the API on the custom domain. In the example configuration I used a base path so that I can potentially have multiple API Gateway definitions on the same custom domain. That means that the path to the API will have to also use the base path. As an example if the API Gateway definition was a path of /dostuff the resulting full URL for the example shown would be:

https://api.example.com/app/dostuff

Don’t forget that the create_domain step will take time, like 40 minutes, and nothing will work until that completes.