API Gateway with Custom Domains in Serverless for Beginners

In the age of micro-services, developers create a lot of apis which are often scattered all over the place. We had a similar problem, our number of APIs grew fast with time. Just a better way to manage these APIs is to organize them under a custom domain and have them served in a more readable manner. This blog will walk you through the same process, specific to the serverless framework.

We will be using the Serverless Domain Manager plugin to achieve this.

Installing the plugin in your serverless application

You can achieve this by-

serverless plugin install --name serverless-domain-manager

Deciding upon a subdomain to host your APIs

If you own a domain name, you need to decide on a sub-domain to host your APIs base URL, it could be something like api.example.com

Additions to the serverless.yml

Add the plugin declaration, as follows -

plugins:
  - serverless-domain-manager

Now is the time to add configuration -

custom:
  stage: ${opt:stage, 'dev'}    # This is declaring a variable which gives you the current stage, defaults to 'dev'
  domains:
    dev: api-dev.example.com    # This will be your base url for dev apis
    prod: api.example.com       # This will be your base rul for prod apis
  customDomain:
    domainName: ${self:custom.domains.${self:custom.stage}}  # This selects the domain name from custom->domain based on the variable custom=>stage
    basePath: 'basepath-of-your-choice'     # This will be your base path after the base url eg, api.example.com/basepath-of-your-choice/routes
    createRoute53Record: true

‍

Now is the time to take a pause, you will realise that you have setup the configuration that you need but the sub-domain still doesn't exist in Route53.

Create Sub-domain in Route53

I will not list down any complicated set of instructions here, all you need to do is run serverless create_domain

You just need to do this once, when publishing any of your APIs for the first time.

This will create your sub-domain given that your aws credentials have enough access to do it in Route53 and you have the hosted zone setup in Route53

Deploy your API

All done, you just have to do a sls deploy now.

You can add this configuration for all your APIs.

‍

In case you have more than one types of APIs in your Serverless Application, use the below example to deploy to custom domains -

custom:
  stage: ${opt:stage, 'dev'}
  wsdomains:
    dev: ws-dev.example.com
    prod: ws.example.com
  domains:
    dev: api-dev.example.com
    prod: api.example.com
  customDomain:
    rest:
      domainName: ${self:custom.domains.${self:custom.stage}}
      basePath: 'chatserver'
      createRoute53Record: true
    websocket:
      domainName: ${self:custom.wsdomains.${self:custom.stage}}
      basePath: 'chat'
      createRoute53Record: true
      endpointType: 'regional'

‍

Visit Gushwork.ai to delegate your tasks now!