How to setup API Gateway Custom Domain using CloudFormation

API Gateway Custom Domain using CloudFormation
Sharing is Caring:

Create API Gateway Custom Domain using CloudFormation

In this quick post, you will learn to create a custom domain name for your API Gateway using CloudFormation. You will also learn to map your micro services 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.

Prerequisite:

  • An AWS Account
  • 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 custom domain?

Why Custom Domain?

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

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

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

how did you feel by looking at the domain?

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 then 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 have learn to create an edge optimized custom domain name.

Steps to create API Gateway Custom Domain using CloudFormation?

  1. Create certificate for your domain
  2. Create Custom Domain name
  3. Create Route53 record to map API gateway cutom domain name with your url
  4. Create a BasePathMapping for each microservice you want to map with this domain

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

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

Let’s start with the steps…

Step 1: Create 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: 
      ValidationMethod: 'DNS'
Outputs:
  CertificateArn:
    Description: "ACM Certificate ARN"
    Value: !Ref AcmCertificate

Save above template and navigate to north virginia region

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

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

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

Change the parameters default value for Domain, HostedZoneId CertificateArn noted in earlier step. 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 API gateway and navigate to 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 you 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

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.

Conclusion:

In this quick article, we learnt to create an ACM certificate and created 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 API , base path is must.

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

I hope this post was useful to you. In case of any issue please add in 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 –
  • Subscribe to our newsletter to get notified each time we post new content.
  • Share this post with your friends and colleagues

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

Also Read:

Sharing is Caring:

2 thoughts on “How to setup API Gateway Custom Domain using CloudFormation

  1. Thanks for the tutorial. Two questions regarding the bas mapping:
    * do you need base mapping file if you just want the domain name to only be applicable to the one api gateway api? or should I always include a base mapping and set the BasePath to “” (as mentioned) to make it apply to the one api?
    * where did you define the ProductManagementAPI you refer to for the RestApiId? Is this the id of the api gateway api?

    1. Thank you Tatenda,

      Please find my answer below:
      * do you need base mapping file if you just want the domain name to only be applicable to the one api gateway api? or should I always include a base mapping and set the BasePath to “” (as mentioned) to make it apply to the one api? : You can skip base path mapping altogether and it will be served on root domain or you can specify “” which means the same But I agree that skipping it altogether would be clean option
      * where did you define the ProductManagementAPI you refer to for the RestApiId? Is this the id of the api gateway api? : ProductManagementAPI is the API Id of rest API. Thank you for pointing this out. I will add a small explanation in the post as well

Leave a Reply

Your email address will not be published. Required fields are marked *