Route API Gateway API to a Custom Domain Name Using Route53

Typically you can invoke your API using a URL of the following format after deploying:

https://api-id.execute-api.region.amazonaws.com/stage

Even though the region and stage are relatively stable and easy to remember, the api-id is kinda like a random number for each API created and is really not user friendly when it comes to memorizing. It would be great if we can invoke the API using a custom domain name, for example:

https://www.example.com/myapi

or something like

https://myapi.example.com

I have an API Gateway API which triggers a Lambda function to serve Gatsby site and backend APIs and a domain registered with Route53. My goal is to route the custom domain to the API Gateway API so whenever I want to visit the site and use the API service, I can use the custom domain name directly.

Here is a quick summary of the steps you need in order to achieve this:

1. Decide the custom domain name you want to use.
2. Get an SSL certificate for the domain name in step 1.
3. Create a custom domain name in API Gateway.
4. Create a DNS A record in Route53.

Decide the Custom Domain Name You Want to Use

For demonstration purpose, I decide to use following form i.e. with a subdomain

https://api.example.com

You can choose any other one that works for you. For example if the API you want to map to serves the home page of your website, you may want to map it to

https://example.com

or

https://www.example.com

Get an SSL Certificate for the Decided Domain Name

The reason we have to get an SSL certificate for the custom domain name is that API Gateway will require an ACM certificate when we create custom domain name in API Gateway. My understanding for this requirement is that AWS secures the API endpoints by default after they are deployed. It doesn’t make sense if it allow the APIs to be mapped to an unsecured domain name, i.e. using HTTP protocol instead of HTTPS.

To get an SSL certificate, you can purchase a certificate with ACM (AWS Certificate Manager) directly or get a free one with CAs (Certificate Authority) like Let’s Encrypt, SSL For Free, etc. For demonstration, I’ll apply a free certificate from SSL For Free.

First, go to SSL For Free, enter the domain name you decided in the input box and press the Create Free SSL Certificate button.

Secondly, you have to create a free account in order to proceed. Use a valid email address as it’ll require verification later.

Thirdly, double check the custom domain name you entered in Domains, section, click next step to proceed; check 90-Day Certificate if you want a free certificate, otherwise select 1-Year Certificate, click next step to proceed; leave everything as is in CSR & Contact section, click Next Step; finalize your order, select Free plan and click next step to proceed.

Lastly, go to Certificates section, find your domain in the Issued tab, click on the Install button; select AWS as the server type, then click on the download button.

In the downloaded .zip file there are three files, namely ca_bundle.crt, certificate.crt and private.key. We’ll import them to ACM in the next section.

Create a Custom Domain Name in API Gateway

Well, before we can create a custom domain name in API Gateway, we have to import the certificate we got in the previous section to ACM.

Import SSL Certificate to ACM

First, go to Certificate Manager (ACM) of your region, click on “Import a certificate” button.

Next, we have to provide certificate body, certificate private key and certificate chain to ACM. Here is the mapping of these three fields and the certificate files we got:

Certificate body -> certificate.crt
Certificate private -> key private.key
Certificate chain -> ca_bundle.crt

Copy the file content and paste to corresponding field. Note that you have to delete the extra lines, if exist, after — — — END CERTIFICATE — — — .

Add any descriptive tags you like and then review and import the certificate.

Create a Custom Domain Name in API Gateway

Now we have everything to create the custom domain.

First, go to API Gateway page of your region, select “Custom domain names” on the left sidebar.

Secondly, click on the create button.

Thirdly, enter the custom domain name (It should be exactly the same as the one we applied for SSL certificate earlier); check the options that fits your need and select the certificate.

Finally, press the create button to create this custom domain.

Wait, we didn’t specify any API when creating the custom domain, right? How can this domain know which API to call?

It’s true that the creating custom domain name page doesn’t provide this option. If we do no additional configuration here and go to Route53 to configure the A record, we’ll wait forever for it to work.

The idea of creating custom domain names is that we can later map the APIs to the custom domain names.

In order to map the APIs we want to use to the custom domain name, click on the Create domain names on the left sidebar again. This time we can see the custom domain we just created. Click on the custom domain, we can check the basic information of this custom domain (pay special attention to the API Gateway domain name as we’ll use it later in Route53). Scroll to the bottom we can see the API mappings section is empty. Click on configure API mappings button, select the API we want to map to this domain and optionally supply the path we want to mount the API on and save.

Now we are done with API Gateway part.

Create a DNS A record in Route53

First, go to Route53, select Hosted zones in the left sidebar, then click on the domain you want to route the API Gateway API.

Secondly, click on the create record button, choose simple routing and click on next.

Thirdly, click on the define simple record button. In the record name section, type the same subdomain you used in the custom domain name. In our example, it’s api. Select “A — Routes traffic to an IPv4 and some AWS resources” as record type. Select “Alias to API Gateway API” in Value/Route traffic to. Then select the API Gateway region and choose the custom domain name id (this is the id shown in the custom domain name information page in API Gateway).

Finally click on the create records button. Wait for around 60 seconds, visit the following URL we just created in browser:

https://api.example.com

Limitation: the A record created this way only works when we access the URL using HTTPS protocol. We’ll receive an ERR_CONNECTION_REFUSED error if use HTTP. In order to fix this, we can use AWS CloudFront to redirect all HTTP traffic to HTTPS. While the con is AWS CouldFront is only free for the first 12 months for a newly opened account.

Read More

Setting up custom domain names for REST APIs

Configuring Route53 to route traffic to a regional API Gateway endpoint