Create API Gateway Custom Domain using CloudFormation

In this quick post, you’ll learn to create a custom domain name for your API Gateway using CloudFormation. You will also learn to map your microservices to the same domain that you create using base path mapping.

Don’t worry if you don’t understand something now, you will do things step by step.

Don’t want to miss any posts from us? join us on our Facebook group, and follow us on Facebook, Twitter, LinkedIn, and Instagram. You can also subscribe to our newsletter below to not miss any updates from us.

Prerequisite:

• An AWS Account: See How to Setup AWS Free Tier Account in Right Way
• A Registered internet domain name(Route53 registered for this tutorial)
• Basic knowledge of API Gateway, Route53 and CloudFormation

Before we start creating an API gateway custom domain name using CloudFormation, let’s look at the point- why a custom domain?

Why Custom Domain?

Well, when you create an API with an API gateway, it does provide you with a default domain name like https://api-id.execute-api.region.amazonaws.com/stage

Here, api-id is actually your API Id, the region is the region you provided while creating API and the stage is the stage in which you deploy like dev, non-prod or prod.

This can look like this: https://yl1n03yf3m.execute-api.eu-west-1.amazonaws.com/Prod/product/{productId}

how did you feel by looking at the domain?

Are you going to remember it next time when I ask?

I am sure, it didn’t look very friendly. Did it?

So, to sum up, these default domain names are very difficult to remember and not at all user-friendly. That’s why it’s better to use an alternate and more friendly domain name like api.cloudkatha.com

I am sure, you liked it more than the default one provided by API Gateway. 😛

Edge Optimized or Regional Custom domain

When you create a custom domain in API Gateway you get two options

• Edge Optimized: Supports only REST API
• Regional: Supports REST, HTTP and WebSocket API

In this tutorial, you will learn to create an edge-optimized custom domain name.

Steps to Create API Gateway Custom Domain using CloudFormation?

1. Create a certificate for your domain
2. Create a custom domain name
3. Create a Route53 record to map the API gateway custom domain name with your URL
4. Create a BasePathMapping for each microservice you want to map with this domain

Please note that the edge-optimized custom domains only supports ACM certificate in North Virginia(us-east-1) region.

So if you have your API in a different region then first create a certificate in the North Virginia region and refer to the ARN in your stack to create a custom domain.

Let’s start with the steps…

Step 1: Create a certificate for your domain

In the below CloudFormation template, change parameters Domain and HostedZoneId’s default value with your domain and route 53 hosted zone id in which validation record needs to be added.

---
AWSTemplateFormatVersion: 2010-09-09
Parameters:
  Domain:
    Description: "Domain for API"
    Type: String
    Default: api.cloudkatha.com
  HostedZoneId:
    Description: "Hosted Zone Id in which you want to add record"
    Type: String
    Default: XJGYF3453769GVHJGI6
Resources:

  AcmCertificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: !Ref Domain
      DomainValidationOptions:
        - DomainName: !Ref Domain
          HostedZoneId: !Ref HostedZoneId
      ValidationMethod: 'DNS'
Outputs:
  CertificateArn:
    Description: "ACM Certificate ARN"
    Value: !Ref AcmCertificate

Save the above template and navigate to the North Virginia region

Go to the CloudFormation console and create a stack with the saved file.

After successful stack creation, navigate to the output tab and note down the Certificate ARN because we will need that in the next step. For step-by-step ACM certificate creation, you can check out our tutorial on ACM Certificate creation

Steps 2 & 3: Create API Gateway Custom domain and Route53 Record

Change the parameters default value for Domain, HostedZoneId CertificateArn noted earlier. Once changed, save and run the template in the region where you have all your API deployed

---
AWSTemplateFormatVersion: 2010-09-09
Parameters:
  Domain:
    Description: "Domain for API Gateway API's"
    Type: String
    Default: api.cloudkatha.com
  HostedZoneId:
    Description: "Hosted Zone Id in which we want to add A record"
    Type: String
    Default: XJGYF3453769GVHJGI6
 CertificateArn:
    Description: "ACM Certificate ARN"
    Type: String
    Default: 'arn:aws:acm:us-east-1:{AccountId}:certificate/{Id}'

Resources:  
  ApiGWCustomDomain:
    Type: AWS::ApiGateway::DomainName
    Properties: 
      DomainName: !Ref Domain
      CertificateArn: !Ref CertificateArn
      EndpointConfiguration:
        Types:
          - EDGE
      SecurityPolicy: TLS_1_2
          
  Route53RecordSetGroup:
    Type: AWS::Route53::RecordSet
    Properties:
      Name: !Ref Domain
      Type: A
      HostedZoneId: !Ref HostedZoneId
      AliasTarget:
        DNSName: !GetAtt ApiGWCustomDomain.DistributionDomainName
        EvaluateTargetHealth: false
        HostedZoneId: !GetAtt ApiGWCustomDomain.DistributionHostedZoneId
        
         

Now If you go to the API gateway and navigate to the custom domain name you can see your newly created custom domain there.

Now it’s time for us to add API mapping.

Step 3: Add API BasePath mapping

Wherever you have your API defined add base path mapping as below

  APIMapping:
    Type: AWS::ApiGateway::BasePathMapping
    Properties: 
      BasePath: product
      DomainName: api.cloudkatha.com
      RestApiId: !Ref ProductManagementAPI
      Stage: Prod

The resulting path after adding the mapping: api.cloudkatha.com/product

Note: Please note that, If you don’t set any base path mapping(By making it ” “) under a custom domain name, the resulting API’s base URL is the same as the custom domain (for example, https://api.cloudkatha.com). In this case, the custom domain name can’t support more than one API.

Related: How to Deploy CloudFormation Template using AWS CLI

Conclusion:

In this quick article, we learnt to create an ACM certificate and created a custom domain using that certificate ARN.

After creating the domain, we saw how to create a route53 record to map our URL with API. Finally, we added a base path mapping and also learnt that in order to support multiple APIs, a base path is a must.

Please note that you can have multiple APIs under the same custom domain name by adding multiple basepath mapping.

The template was in YAML format. If you need it in JSON, check out my post on How to Convert a CloudFormation Template from JSON to YAML and Vice Versa.

I hope this post was useful to you. In case of any issues please add them in the comment section. We would love to resolve your issue.

You can motivate me and help me get better by –

• Adding a comment on this post on what you liked and what can be improved.
• Follow Cloudkatha on –
  • Facebook
  • Twitter
  • LinkedIn
  • Instagram
• Share this post with your friends and colleagues

Please share your feedback and help us get better with time 🙂

Also Read:

• Create an S3 Bucket Using CloudFormation
• Install OpenJDK 11 on Amazon Linux 2
• Create DynamoDB Table Using CloudFormation
• Send a Message to SQS using Node.js Lambda
• Create an AWS Lambda Using Java
• Most Common Cyber attacks You should Know