Skip to main content

AWS Solutions Library

Guidance for Custom Domain Names on Amazon API Gateway Private Endpoints

Overview

This Guidance shows how to create and facilitate access to private REST APIs on AWS. By using Amazon API Gateway, you can confirm that all traffic to your private API uses a secure connection and stays within the AWS network and your virtual private cloud (VPC). This approach protects your API from the public internet and maintains the confidentiality of transmitted traffic, helping you meet regulatory and security requirements. Additionally, while API Gateway only supports custom domain names for public API endpoints, this solution implements a custom domain name for private APIs, so you can provide your API users with logical URLs that are easy to remember.

How it works

These technical details feature an architecture diagram to illustrate how to effectively use this solution. The architecture diagram shows the key components and their interactions, providing an overview of the architecture's structure and functionality step-by-step.

Download the architecture diagram

Get Started

Deploy this Guidance

Use sample code to deploy this Guidance in your AWS account
Sample code

Well-Architected Pillars

The architecture diagram above is an example of a Solution created with Well-Architected best practices in mind. To be fully Well-Architected, you should follow as many Well-Architected best practices as possible.

The Guidance uses infrastructure as code and bash scripts to automate deployment and updates to the deployment configuration, helping you avoid human errors and quickly make improvements. Additionally, you can integrate these elements into your existing continuous integration and continuous delivery (CI/CD) processes.

This Guidance uses variables and configuration files to store settings, and an included bash script handles deployments. You can incorporate the script, variables, and configuration files into your existing CI/CD processes.

Read the Operational Excellence whitepaper

You can use granular API Gateway resource policies to limit the methods, paths, stages, and VPC endpoints that can be used, helping you control access to private resources. This Guidance does not store sensitive data. However, for sensitive data in transit, ACM provides a trusted certificate for client applications to use for connections to the ELB. Additionally, PrivateLink and the NGINX container hosted in Amazon ECS help ensure data in transit remains encrypted.

Read the Security whitepaper

The Guidance deploys ELB, Amazon ECS, and PrivateLink workloads across multiple Availability Zones. Amazon ECS deploys with two tasks by default, and ELB health checks make sure that the Amazon ECS tasks are working properly. Additionally, the ACM implementation uses DNS validation, which requires an available, public Route 53 zone for the custom domain or the parent domain. You can also enable cross-account private API endpoint access; this Guidance does not support cross–AWS Region access.

Read the Reliability whitepaper

The Guidance uses on-demand services and automatic scaling to adjust to demand and optimize your resource utilization. The metric values that invoke scaling are customizable, so you can configure them for optimal performance for your specific use case.

Read the Performance Efficiency whitepaper

The Guidance uses Fargate for Amazon ECS compute and uses tasks that automatically scale to meet demand. This helps you optimize resources and minimize compute costs. Additionally, these Amazon ECS tasks scale based on configurable usage metrics, so you can match the minimum and maximum resources to your needs.

Read the Cost Optimization whitepaper

The Guidance uses on-demand services and automatic scaling to adjust to demand. As a result, resource usage is reduced, minimizing the energy use for your workloads. Additionally, you can configure the scaling metrics to the minimum capacity required by your use case, helping you further avoid overprovisioning.

Read the Sustainability whitepaper

Disclaimer

The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.

References to third-party services or organizations in this Guidance do not imply an endorsement, sponsorship, or affiliation between Amazon or AWS and the third party. Guidance from AWS is a technical starting point, and you can customize your integration with third-party services when you deploy the architecture.