Best Practices for Designing Amazon API Gateway Private APIs and Private Integration | AWS Whitepaper Summary

In this whitepaper summary (originally created by Takaki Matsumoto), we will introduce the best practices for deploying private APIs and private integrations in API Gateway, and discusses security, usability, and architecture.

Introduction

Private APIs provide a secure means to invoke APIs via an interface VPC endpoint. API Gateway private integration makes it simple to expose your HTTP/HTTPS resources integration can integrate with private APIs, so the APIs can send requests to a Network Load Balancer (NLB), or through Application Load Balancer (ALB) or AWS Cloud Map for HTTP APIs. Private Integration forwards external traffic sent to APIs to private resources, without exposing the APIs to the internet.

Amazon API Gateway

Amazon API Gateway is a fully managed service that helps you easily create, publish, maintain, monitor, and secure APIs at any scale. This service offers the following types of APIs:

• REST API, which comes with multiple endpoint types, like edge-optimized, regional, and private (the one we will focus on here)
• WebSocket APIs, which is preferred for building real-time, 2-way communication apps. Private integration is provided by creating a route with VPC link.
• HTTP APIs, which is the newest offering in API Gateway, with support for auto deployment, CORS and enhanced performance. Private integration is support through ALB, AWS Cloud Map, and NLB.

REST API

To make APIs accessible only from Amazon VPCs, you can use REST APIs with the private endpoint type. The traffic to the APIs will not leave the AWS network. There are three options to invoke a private API through different domain name system (DNS) names.

Resource-Based Policy

Resource-based policies are attached to a resource like a REST API in API Gateway. For resource-based policies, you can specify who has access to the resource and what actions are permitted. Private APIs require the use of a resource policy, and Deployments without a resource policy will fail.

Private Integration

Private integration is used to allow traffic routing from API Gateway to VPCs, which is achieved using VPC links and VPC endpoint service that is tied to NLBs. A common use case is to invoke EC2-hosted apps behind NLB through VPC links.

Sample Architecture Patterns

Basic Architecture

Points of interest

• Security group attached with the endpoint must allow TCP port 443.
• Private API resource policy must allow requests from VPC and interface VPC endpoint.

Cross-Account Architecture

Points of interest

• Both accounts must exist in the same region.
• Private API resource policy must allow access from other account’s VPC or interface VPC endpoint.

On-Premises Architecture

Points of interest

• Use Route53 alias records for access through web app to avoid CORS issues.

Private Integration Architecture with ECS

Points of interest

• Use NLB to route traffic to Amazon ECS cluster

WebSocket API

This API type of API Gateway allow creating APIs that is accessible using WebSocket protocol. WebSocket APIs allow bidirectional connections that is often used with real-time apps, such as chats apps, multiplayer games, and financial trading apps.

Private Integration

The same design principles apply to WebSocket APIs as for REST APIs, except for response handling, which is optional in WebSocket APIs.

Sample Architectural Pattern

Points of interest

• NLB has TLS listener on TCP port 443.
• The target group points to Amazon ECS service.

HTTP API

This API type is the newest of API Gateway, which comes with enhanced features, performance, easier developer experience, and reduced request pricing.

Private Integration

HTTP APIs offers three types of private integration targets, which widen the design choices according the backend service to create VPC endpoints.

• NLB: with a TCP or TLS listener.
• ALB: with a HTTP or HTTPS listener.
• AWS Cloud Map, with Service Discovery features.

Sample Architectural Patterns

ALB Architecture (ECS)

Points of interest

• ALB uses path-based routing rules to route traffic to two different ECS services.

Cloud Map Architecture (Microservices)

Points of interest

• Service discovery in Cloud Map allow routing requests to different endpoints.

Security

Private APIs and associated integration comes with extra security, due to limited access to resources within a private network. The following tables lists supported authorization options for all API Gateway offerings:

• IAM: which serves with all API types.
• Amazon Cognito: which serves with REST and WebSocket, and commonly used with web and mobile apps
• Lambda: also works with all API types, and allow developers to design business logic around authorization.
• JWT: which serves with HTTP API only.

Cost Optimization

As mentioned before, HTTP APIs offers the lowest pricing tiers if the application design accepts both REST APIs and HTTP APIs. Serverless Application Lens offers cost optimization practices for, like cost-effective resources, matching supply and demand, and expenditure awareness.
The following list show a highlight of the pricing tiers for REST and HTTP, but more information can be found at Amazon API Gateway Pricing:

• REST API: ranging from one million calls/12 months at free tier to over 20 billion requests/month with $1.15 per million.
• HTTP API: ranging from one million calls/12 months at free tier to over 300 million requests/month at $0.9 per million Private Integration in REST and WebSocket requires NLB, but it’s billed per hour. For infrequent usage of the APIs, a VPC-enabled Lambda function is more cost effective, because it’s billed per request.

Conclusion

Amazon API Gateway provides different API types and endpoint types. This paper primarily covered private API and integration design patterns, and best practices. Additionally, it covered security and cost optimization. You can leverage the information provided in this whitepaper to determine the best-suited architecture for your application.

References
Original Whitepaper