Custom Domain Names for API GW

AWS API Gateway is simple and easiest way to rollout your own APIs. Combined with Lambda (Serverless), it’s good alternative than hosting your own services cluster for small scale projects but depending on use case it can do big things as well.

When you create an API endpoint AWS creates endpoint as https://<api-id>.execute-api.<region>.amazonaws.com/<stage>. If you are exposing this to your customers, say you are creating public endpoint and want to have something fancy like https://api.example.com then you would need to create a custom domain name in API GW.

Creating custom domain name for API GW is pretty simple and straight forward. But if you look in to AWS documentation on creating custom domain for API GW, it has too much information to cover all the advanced topics like importing your own certificates, create edge optimized domain, etc.. so if you are new to this area that’s too much to read.

If you are looking to simply have custom domain name for API GW, you can do so in three simple steps. Yes, it’s that simple. Usually when you create API GW, AWS creates edge optimized GW so in this example I’m also going to cover creating a custom domain for edge optimized API GW.

Tip: You cannot have custom domains for Private end point type. Only Edge Optimized and Regional are supported.

I will be using namecheap as hosting provider for the custom domain provider but usually process is similar with any other hosting provider. In addition you can purchase your domain name from Amazon as well. In my experience you can always buy domain at a cheaper price than Amazon from vendors like namecheap, godaddy, etc.. so the decision is up to yours.

Step 1: Create certificate via ACM (AWS Certificate Manager)

1. Go to ACM console
2. Make sure you are in the us-east-1 region otherwise you cant create custom domains for edge optimized API GWs
3. Click Request Certificate and select Request Public Certificate option
4. Add your domain name api.apigateway.com for example
5. Use either DNS or Email validation

when you use DNS validation, you need create a CNAME alias in your hosting provider using name and value provided by AWS after creating the certificate. Below is the screenshot of what it would look like after you request the certificate.

When you are adding this information in to the DNS settings of your hosting provider make sure you remove api.apigateway.com from you name config and add it as below (below is the DNS settings page in namecheap hosting provider)

Using email validation is much easier, if you are the owner of custom domain. AWS would email you a link to click and approve the certificate so you don’t need to go through the hassle of configuring DNS setting as above. But for that you will be receiving emails directed to admin, administrator, hostmaster, webmaster, postmaster @yourdomain.com

In addition to creating a certificate in ACM you can upload your own certificate but why bother as AWS public certificates are not charged.

Once this is done, your certificate will ready to be used.

Step 2: Create custom domain in API GW

1. Go to API GW console and select Custom Domain Names and click create
2. Use the full domain name you want to use for this API. For example, api.example.com
3. Select Edge Optimized as the endpoint type
4. On the ACM certificate dropdown select the certificate you just created and validated
5. Click create
6. Select the created custom domain and then you need to configure API mappings to map your domain to relevant API state — for example, you may have one API endpoint for production and another one for dev
7. In the mapping window, select the API you want to expose and stage of the selected API and click save
8. You need to find out the API Gateway domain name of the custom domain you’ve created. You can find this out by selecting the custom domain name you’ve just created. Usually it looks like <some ascii chars>.cloudfront.net. Copy this as you’d need this in the step 3 below.

Now you are completed with all the steps that you need to do from AWS side.

Step 3: Configure DNS settings

1. Go to DNS settings page of your hosting provider
2. Create a new CNAME alias by using the custom domain name and pointing it to Cloudfront domain name copied from step 2 above.
3. In namecheap the configuration would look like this. Save All Changes to continue

So this is it. Only simple 3 steps. In summary, you need to create a certificate for your API — and you can do it via ACM, next you need to create custom domain for your API in APIGW, finally you need to add DNS settings to route requests coming to custom domain to relevant API GW endpoint.

This is bear minimum for you to have your own custom domain for API GW. You can read the advanced options under AWS documentation.

1. Request Public Certificate: https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html
2. API GW Custom Domain: https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html

Let me know if this guide helps you in setting up your APIs.