Skip to main content

Custom Domains

Custom Domain on API Gateway and CloudFront​


### 1. Set up DNS records on Route53
  • If you domain name provider is not Route53, first add the domain name in Route 53.
    • Route 53 will generate NS records (name servers) which you will need to add to your domain wherever it resides. Just add the Name Servers in your domain name provider for that domain.
  • Add an Alias A record for www.chaine.dev`` that routes to chaine.dev`

2. Create a Certificate​

  • Head over to Certificate Manager and create a certificate for your domain. Make sure to add the additional names:
chaine.dev
*.chaine.dev  // this will cover all subdomains
www.chaine.dev

Add the end of the certificate creation process, check the button to add the certificate to Route53. If this isn't done automatically, you will need to do it manually or else your site won't be secured by the certificate.

3. Use either a custom url or CloudFront​

There are two ways you can route users to your apigateway resources: 1. Route directly to api-gateway or 2. Use CloudFront. Both have their own pros and cons, research online on what works best for you.

3a. Use API Gateway Custom domain​

See AWS docs here if you want to do wildcard subdomains for infinite api creations without any limits from APIGW

  1. Setup Custom Domain in API Gateway, if you did multiple subdomains per environment, then create those separately (i.e. dev.api.chaineapp.com, staging.api.chaineapp.com, etc..). If you want one subdomain (i.e. api.chaineapp.com) for multiple environments, that is a little tricky to do with Serverless Framework as serverless Framework will deploy a separate api gateway resource for each stage, so you will need to do more R&D on how to do it. You can also check out this this serverless forum post, this guide,
  2. In the API Gateway console, for each domain, create an API mappings (under Custom domain names > select the custom domain > click API mappings)
  3. If you have a subdomain for each stage, just select the API and select the Stage. No need to select the Path. What this will do is for example, for dev, if you have dev.api.chaineapp.com, and apigateway path is putting a /dev, you don't need to add path and also don't need to use the /dev when making an api call. You can just make the api call like: https://api.chaineapp.com/myPath even though the path for dev in api gateway is https://api.chaineapp/com/dev/myPath. The API mapping will take care of the routing to the proper stage.
  4. Finally, make sure you have created an alia A (or CNAME) record for the subdomain path in Route53, to connect it to the proper API gateway resource.

3b. Create CloudFront Distribution​

Create a CloudFront Distribution. The way this setup works is CloudFront will handle all requests from everywhere and then redirect them to where you need them to go. This is done by creating an alias A record that points to the CloudFront distribution in Route53.

  • Enter Origin Domain Name. If your primary domain chaine.dev is pointing to your webpage, then enter that domain here. I.e. if it is your GitHub pages, this would be something like chaineapp.github.io/website. You can change this later, don't worry.
  • Keep all default options, except choose HTTPS Only for Origin Protocol Policy
  • For price class, you can choose U.S., Canada, and Europe if your app isn't needed on all Edge locations to save on costs
  • Add your Alternate Domain Names (CNAMEs). Include these:
chaineapp.com
www.chaineapp.com
*.chaineapp.com
  • Select Custom SSL Certificate and choose the certificate you created earlier
  • Select Security Policy TLSv1.2_2019 or the recommended ones
  • Create this CloudFront

4. Add CloudFront as A record​

Go back to Route53 and add CloudFront as an alia A record. When you select alias, select the option Alias to CloudFront distribution and choose your newly created CloudFront.

Note this may also be possible to do in Serverless.yml, but need more R&D. See here

5. Setup Custom Domain in API Gateway​

Head over to API Gateway and select Custom domain names on the left.

  • Put your domain name, i.e. chaine.dev and click create. It should take 10-12 minutes for it to connect, sometimes faster.

6. Setup API Gateway in CloudFront​

Now, remember CloudFront controls where to route traffic to. So, since traffic to chaine.dev is being routed to your GitHub pages website, you want your API traffic to route to chaine.dev/api

  • In CloudFront, select your distribution
  • Go to Origins and Origin Groups, and click Create Origin
  • Add your API Gateway domain name. It is important to NOT include the https:// or https://wwwelse it won'y work. For example, your origin domain name should be something like:
9b5zity92a.execute-api.us-east-1.amazonaws.com
  • If you have multiple urls for this domain, create an origin for each and enter the url path in the Origin Path. You will create an Origin for each url of your API.
  • Most default options should be good, just avoid HTTP. Then create this origin.

Once you create an Origin, it won't just start working. You have to tell CloudFront which path for chaine.dev should take traffic to your newly created origin.

This is called a Behavior for obvious reasons. Head over to the Behaviors tab and click Create Behavior.

The Path Pattern here refers to the path of your URL, not of your API. When you created your Origin, the Origin Path refers to the path of your API. Notice the difference?

Now lets say you created a staging API origin and want all traffic for staging to go to chaine.dev/api/v1/staging. In the Path Pattern, simply add /api/v1/staging.

For the Origin, you guessed it, select the API Gateway Origin you creaetd earlier, and select Redirects HTTP to HTTPs.

For Allowed HTTP Methods, choose the option that applies for this path. If you will allow users to just GET some data, then you only need the first one. But most APIs that users consume and add data to will have multiple (3rd option).

  • You can get more complex with all the different options, but for simplicity its not needed. Just Create and you're all set.