WebSockets at Scale Using Amazon API Gateway WebSocket APIs

Introduction

Real-time communication is at the heart of modern applications, whether it is a live chat feature, a collaborative document editor, a stock ticker, or an online multiplayer game. Traditional HTTP request-response cycles fall short when data needs to flow continuously and bidirectionally between the server and client. This is where WebSockets shine.

While WebSockets are powerful, running them at scale introduces significant infrastructure challenges: managing persistent connections, handling failover, and ensuring low latency for thousands or millions of concurrent users. Amazon API Gateway WebSocket APIs offer a fully managed, serverless solution that takes the heavy lifting off your plate.

In this blog, we will explore how Amazon API Gateway WebSocket APIs work, how to architect them for scale, and what best practices you should follow to build production-grade real-time systems.

What Are WebSockets and Why Do They Matter?

WebSockets provide a full-duplex communication channel over a single, long-lived TCP connection. Unlike HTTP, which opens a new connection for each request, WebSockets keep the connection open, allowing the server and client to send data independently at any time.

Common use cases include:

• Live chat and messaging applications
• Real-time dashboards and monitoring tools
• Collaborative tools like shared whiteboards or document editors
• Financial data feeds and stock tickers
• Online gaming and live sports scores

The challenge with WebSockets at scale is that each open connection consumes server resources. Traditional server-based WebSocket implementations require sticky sessions, careful load balancing, and manual scaling strategies. Amazon API Gateway eliminates most of these concerns.

Amazon API Gateway WebSocket APIs: An Overview

Amazon API Gateway WebSocket API is a fully managed service that allows you to build real-time two-way communication applications without managing the underlying infrastructure. It acts as a front door for your WebSocket connections and routes incoming messages to backend services such as AWS Lambda, HTTP endpoints, or other AWS services.

Key concepts

Connection Management

When a client connects, API Gateway assigns a unique connectionId. This ID persists for the life of the connection and is used to send messages back to that specific client. Connections are stored and managed by AWS, you do not need to maintain connection pools yourself.

Routes

WebSocket APIs in Amazon API Gateway use routes to direct messages to the appropriate backend. There are three built-in routes:

• $connect — triggered when a client establishes a connection
• $disconnect — triggered when a client closes the connection
• $default — triggered for any message that does not match a custom route

You can also define custom routes based on the content of the message, such as routing a message with action: ‘chat’ to a dedicated AWS Lambda function.

Callback URL

To push a message back to a connected client, your backend uses the Management API endpoint: https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}. A simple POST request to this URL with a payload delivers the message to the client in real time.

Architecting WebSockets at Scale

A production-ready WebSocket architecture on AWS typically involves the following components:

1. Amazon API Gateway + AWS Lambda

Each route ($connect, $disconnect, $default, custom routes) maps to a Lambda function. Lambda scales automatically with the number of incoming connections and messages, making it inherently serverless and scalable.

2. Amazon DynamoDB for Connection Storage

Since AWS Lambda functions are stateless, you need a persistent store for connectionIds. Amazon DynamoDB is the preferred choice due to its low latency, automatic scaling, and tight integration with AWS. When a client connects, store the connectionId (and any session data, such as userId or room) in Amazon DynamoDB. On disconnect, remove the record.

3. Broadcasting Messages

To broadcast a message to all connected clients, for example, in a chat room, your AWS Lambda function queries Amazon DynamoDB for all active connectionIds in that room and loops through them, posting to each connection’s callback URL. Stale connections (where the client has already disconnected) should be handled gracefully by catching 410 Gone errors and deleting those records from Amazon DynamoDB.

4. Amazon SQS or Amazon EventBridge for Async Processing

For high-throughput scenarios, it is a good practice to decouple message ingestion from processing. When a message arrives, AWS Lambda can push it to an Amazon SQS queue or Amazon EventBridge. A separate consumer AWS Lambda then processes and broadcasts the message. This prevents connection handling from being blocked by slow backend logic.

Best Practices for Production Deployments

• Use connection TTLs in Amazon DynamoDB with a TTL attribute to auto-expire stale connection records and reduce storage costs.
• Handle 410 Gone errors gracefully when broadcasting. If a connectionId is no longer valid, clean it up immediately from your data store.
• Enable throttling and quotas on your Amazon API Gateway stage to protect your backend from traffic spikes and abuse.
• Monitor with Amazon CloudWatch. Track custom metrics like active connections, message rates, and Lambda error counts to detect issues proactively.

Limitations to Be Aware Of

While Amazon API Gateway WebSocket APIs are powerful, there are some limits to plan around:

• Maximum connection duration is 2 hours. After this, the connection is automatically closed. Your client should handle reconnection logic.
• Message payload size is limited to 128 KB. For larger payloads, consider sending a reference (e.g., an S3 URL) and letting the client fetch the full content.

Conclusion

Amazon API Gateway WebSocket APIs offer an elegant, serverless approach to building real-time applications at scale. By combining Amazon API Gateway with AWS Lambda for compute, Amazon DynamoDB for connection state, and Amazon SQS or Amazon EventBridge for async message processing, you can build a robust architecture that scales from hundreds to millions of concurrent connections without managing a single server.

Drop a query if you have any questions regarding Amazon API Gateway WebSocket APIs and we will get back to you quickly.