Adding a custom domain to your REST API Gateway on AWS

Custom domain names

When we implement a REST API on AWS using a service called API Gateway, AWS generates a default domain for the stage in the following format:

https://api-id.execute-api.region.amazonaws.com/stag****e

As we can see, there are three pieces of information in this default domain that are variable:

API ID: The identifier of your API generated by AWS;
Region: The region of deployed API;
Stage: Stage name defined by you.

Now, when we use custom domains, we can provide a friendly URL to the clients of our service. Additionally, we can determine a base resource where all requests will be routed. For example:

https://api.example.com/mybashpath

In this article, we will learn how to define a custom domain for our REST API Gateway on AWS.

Prerequisites

At this point, now that we understand what custom domain names are in the context of API Gateway on AWS, we need to define the requirements so that we can proceed with this tutorial. Obviously, we need an account in our Cloud Provider for follow the next steps.

Deployed API Gateway: We will need a REST API implemented, even if the integrations are just mocks;
SSL/TLS certificate: In this case, we will use the ACM (Amazon Certificate Manager) service, where we can publish SSL/TLS certificates;
Hosted zone: Finally, we will need a hosting zone in the AWS DNS service, called Route 53;

Creating our domain

SSL/TLS certificate

Enter the AWS Certificate Manager service;
Click on "Request";
Choose the type of public certificate and click "Next";
Add the domain;
Select the DNS validation method;
Choose the encryption algorithm;
Click "Request" again;

Validate certificate

Now, with the certificate requested, we need to validate it with our domain register. In this context, since we chose to validate via DNS, we need to create a CNAME record with the values generated by AWS in the hosted zone.

The DNS service we are using is already on AWS, Route 53, provides a way for us to create the validation records directly in our hosted zone. Just go to the certificate page and click on "Create records in Route 53" and follow the steps for create records. Then simply wait a few minutes for the certificate to be validated.

Custom domain name

Enter the AWS API Gateway service;
Click on "Custom domain names" and then click on "Create one";
Define the name of your domain;
Choose the TLS version (version 1.2 is recommended as of the publication date of this article);
Choose endpoint type: Regional or Edge-optimized;
Select the SSL/TLS certificate created with ACM;
Done! Now just click on "Create" and we will have our domain finalized.

API Mapping

After the creation and validation of the certificate and the creation of the custom domain, we need to add the mapping of our REST API to the domain. In this scenario:

Click on the domain under "Custom domain names";
Go to the "API mappings" tab and click on "Configure";
Just specify which API it is (remembering that both must be in the same region), the stage and if there is any specific path to which it will be mapped.

Routing traffic to the API

Finally, just go to Route 53 and follow these steps:

Click on "Create a new record";
Choose the record type A;
Enable the alias;
Select the alias routing to the API Gateway service;
Select the region where your API is located;
Select the API;
Save the record.

At this point, you just need to wait a few seconds or minutes for AWS to publish your application, routing the traffic to the API.

Conclusion

Therefore, by following these steps, you have just completed the configuration of your custom domain within AWS. In this way, your clients - wheter mobile apps, web apps or third parties - will have a friendly URL through which they can consume your services.

References

https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html

https://repost.aws/knowledge-center/custom-domain-name-amazon-api-gateway

https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html