Custom Domains - The easy way.

Today, we'll discuss how to set up a custom domain for your APIs deployed via Nitric, specifically on AWS (Amazon Web Services).

Custom domains provide a more professional image and allow for easier access and use by your clients or end users.

AWS Custom Domain Prerequisites

Before you can use custom domains with your APIs on AWS, you must configure your domain or subdomain as a hosted zone in Route 53. Route 53 is a scalable Domain Name System (DNS) web service provided by Amazon Web Services (AWS) that allows the management of DNS records for your domain.

Here are the general steps to create a hosted zone in Route 53:

1. Navigate to Route 53 in the AWS Console and select 'hosted zones' from the left navigation.
2. Click 'Create hosted zone' then enter your domain name and choose the 'Public hosted zone' type.
3. Confirm creation at the bottom right with the 'Create hosted zone button'.
4. You'll then be provided with a set of NS DNS records which you can configure with the DNS provider for your domain.

Once DNS propagation completes, you can use the hosted zone domain or any direct subdomain with your Nitric APIs. Note that if your hosted zone is nitric.io, then nitric.io or api.nitric.io would be supported for APIs, but not public.api.nitric.io as that is a subdomain of a subdomain.

You can learn more about how to configure hosted zones in AWS's documentation on Making Route 53 the DNS service for a domain that's in use or Making Route 53 the DNS service for an inactive domain.

Remember, DNS propagation of the NS records can vary from a few seconds to a few hours due to the nature of DNS. Patience is key!

Nitric and Custom Domains

Nitric is a cloud-agnostic framework that simplifies the process of deploying and managing your APIs. While Nitric's default setting assigns a domain provided by the target cloud provider, you can opt to deploy your APIs with predefined custom domains. These can be specified for each API in your project's stack files. As of now, custom domain support is only available for AWS deployments.

Configuring Custom Domains with Nitric on AWS

Setting up your custom domain involves modifying your project's stack file. Here's an example of a nitric-prod.yaml stack file that configures a custom domain for an API:

name: my-aws-stack
provider: nitric/aws@0.30.0
region: ap-southeast-2

# Add a key for configuring apis
apis:
  # Target an API by its nitric name
  my-api-name:
    # provide domains to be used for the api
    domains:
      - test.example.com

The my-api-name value under the apis section is the nitric name of your API, and test.example.com is the custom domain you wish to use.

Setting up a custom domain for your APIs using Nitric and AWS not only lends a more professional aesthetic to your APIs, but also ensures more accessible usage for your end users. So, take advantage of this feature to optimize your cloud deployments.