AWS’s API Gateway is great as a front end for Lambda functions and other AWS services. However, the default endpoint is a subdomain of amazonaws.com, which isn’t user friendly. We’ll show you how to fix and set up a custom domain.

You’ll need ownership of the domain name you wish to use for the API. You’ll probably want to put this on a subdomain like api.example.com. To do this, you’ll need to do two things: request an SSL certificate from AWS Certificate Manager (ACM) to secure requests made to the API, and update your DNS configuration to point to API Gateway.

Sign in and head over to the ACM Console. From here, select “Request A Certificate,” and specify “Public” as the type.

Next up, enter in the domain names you’d like to use for this certificate. You can add multiple domains here, but one is probably enough, as API stages are split up by sub-URLs anyway.

You have two options for validation. The first will require you to update your DNS configuration with a CNAME record. The second will send a verification email to the email you have on contact for the domain. This won’t work if your email isn’t visible from who.is, which will happen if you have WhoisGuard protection.

It may take a few minutes for changes to propagate if you’re using a third-party registrar. Once validated, your certificate should change status to “Issued,” and will be ready to link to API Gateway.

Switch over to the API Gateway console, and click “Custom Domain Names” in the sidebar. Create a new one, enter in your domain name, and select the certificate you just created. You’ll also need to make sure you have the correct API type selected.

Click create, and a new domain should show up in the list. Click on “Edit” to add a path mapping. This will link a specific subdomain (for example, api.example.com/v1/) to the API and stage you choose.

It would probably be a good idea to create different paths for different API stages, such as a development path for the $default stage, and a production path for the user-facing stage.

Once created, copy the “Target Domain Name” value. This is what you’ll need to update the DNS configuration (not the API endpoint itself).

Linking Your DNS to API Gateway

You’ll notice at this stage that if you visit the URL in your browser, nothing will happen. API Gateway is configured to use your domain securely, but it isn’t receiving any traffic because the DNS isn’t pointing anyone anywhere.

For third-party DNS, you’ll have to use a CNAME record. This maps a domain name to another domain name, but does require an extra DNS lookup. Paste in the “Target Domain Name” value for the custom domain you set up in API Gateway.

If you’re using Route 53, the configuration is simpler. You can achieve the same effect in one lookup using an A record set to “Alias” mode, a special record type that allows you to map the record directly to an AWS resource name. Simply select the API from the dropdown list, and click create.

Changes will take a bit to propagate, but your API should now be available from your domain name. If it’s not working, double-check to make sure you’re connecting over HTTPS, as it won’t accept non-secure connections.