API Gateway WebSocket API: What It Is and When to Use It

Definition

An Amazon API Gateway WebSocket API is a managed AWS service that provides a persistent, bidirectional communication channel between clients and a serverless backend. It simplifies the development of real-time applications by handling connection management, data framing, and scaling, allowing developers to focus on application logic using backend services like AWS Lambda.

How It Works

A WebSocket API maintains a stateful, long-lived connection, unlike the stateless request-response model of REST or HTTP APIs. This full-duplex communication allows the backend to push messages to clients without waiting for a client request, enabling real-time data exchange.

Architecture and Request Flow:

1. Connection: A client initiates a WebSocket connection by sending an upgrade request to the API Gateway endpoint. API Gateway handles the WebSocket handshake.
2. The $connect Route: When a connection is established, API Gateway invokes the integration associated with the predefined $connect route. This is typically an AWS Lambda function used for authenticating the user and storing the unique connectionId in a database like Amazon DynamoDB.
3. Message Routing: When a connected client sends a message, API Gateway uses a route selection expression (e.g., request.body.action) to parse the incoming JSON message and determine which route to invoke. You can define custom routes (e.g., sendMessage, getHistory) that map to different backend integrations (like distinct Lambda functions) to handle specific business logic.
4. Backend Integration: The matched route's integration (e.g., a Lambda function, an HTTP endpoint) is invoked with the message payload. The backend processes the message, performs actions like storing chat messages or fetching data, and can send messages back to clients.
5. Sending Messages to Clients: The backend cannot send a message directly through the open WebSocket connection. Instead, it must use the AWS SDK to call the API Gateway Management API's @connections endpoint (POST /@connections/{connectionId}). This requires the connectionId of the recipient, which is why it's crucial to store it during the $connect phase.
6. Disconnection: When a client disconnects, API Gateway calls the integration for the $disconnect route. This triggers a cleanup process, such as a Lambda function that removes the connectionId from DynamoDB.
7. Default Route: If a message arrives and the route selection expression does not match any custom routes, the $default route is invoked for fallback processing.

Key Features and Limits

• Serverless Model: No servers to manage for handling connections; scales automatically.
• Backend Integrations: Natively integrates with AWS Lambda, Amazon Kinesis, and any public HTTP endpoint.
• Authentication & Authorization: Supports AWS Identity and Access Management (IAM) for signing requests and AWS Lambda authorizers for custom, token-based (e.g., JWT) authentication on the $connect route.
• Custom Domain Names: You can associate a custom domain name with your WebSocket API.
• Logging and Monitoring: Integrates with Amazon CloudWatch for logging API calls and monitoring metrics.

Service Quotas (as of 2026):

• Message Size: Maximum frame size of 32 KB, with a total message payload limit of 128 KB. Messages are metered in 32 KB increments.
• Connection Duration: Maximum idle connection time is 10 minutes. The maximum total connection duration is 2 hours.
• New Connections Rate: 500 new connections per second, per account, per region (can be increased).
• Concurrent Connections: No hard limit on the number of concurrent connections, but constrained by the new connection rate.
• API Requests/Throttling: 10,000 requests per second (RPS) with a burst capacity of 5,000 RPS, applied at the account/region level.

Common Use Cases

• Real-Time Chat Applications: Enables instant, two-way message delivery between users. The backend can broadcast messages to all users in a chat room by retrieving their connection IDs and sending a message to each.
• Live Dashboards and Event Feeds: Pushing live sports scores, financial market data, or application monitoring metrics to a web dashboard without requiring the client to constantly poll for updates.
• Second-Screen Experiences: Synchronizing content between a live broadcast (like a sporting event or TV show) and a mobile app, allowing for real-time polls, stats, and interactive content.
• Multiplayer Gaming: Facilitating low-latency communication of player states and actions between game clients and the game server.
• IoT Device Control: Sending commands to and receiving real-time status updates from connected IoT devices, although for large-scale IoT, AWS IoT Core is often a better fit.

Pricing Model

API Gateway WebSocket APIs have a pay-per-use pricing model with no minimum fees, based on two primary metrics.

1. Messages: You are charged per million messages sent and received. Messages are metered in 32 KB chunks.
2. Connection Minutes: You are charged per million connection minutes, representing the total duration all clients are connected to your API.

Free Tier: The AWS Free Tier for new accounts includes 1 million messages and 750,000 connection minutes per month for the first 12 months.

Data Transfer: Standard AWS data transfer charges apply for data transferred out to the internet.

For detailed and up-to-date pricing, always consult the official AWS API Gateway Pricing page and use the AWS Pricing Calculator.

Pros and Cons

Pros:

• Fully Managed & Scalable: AWS handles the underlying infrastructure for managing persistent connections, allowing you to scale to millions of users without provisioning servers.
• Serverless Integration: Tight integration with AWS Lambda makes it easy to build event-driven, serverless backends.
• Cost-Effective: The pay-per-use model can be very cheap for applications with sporadic traffic, as you don't pay for idle infrastructure.
• Simplified Development: Abstracting away the complexity of WebSocket server management significantly speeds up development for real-time features.

Cons:

• Connection State Management: API Gateway itself is stateless. You are responsible for managing connection IDs and any associated user metadata, typically requiring a database like DynamoDB which adds complexity and cost.
• No Native Broadcast: The service does not have a built-in broadcast or pub/sub mechanism. To send a message to multiple clients (e.g., in a chat room), you must iterate through their stored connection IDs and make a separate API call for each one.
• Service Limits: The 2-hour connection limit and 128 KB message size can be restrictive for certain use cases that require very long-lived connections or large data transfers.
• Potential for Complexity: While simple to start, managing routes, authorizers, and the callback mechanism for a complex application can become challenging.

Comparison with Alternatives

• Application Load Balancer (ALB): An ALB can load balance WebSocket traffic at Layer 7 to backend targets like Amazon EC2 or Amazon ECS. Unlike API Gateway, an ALB is not a managed API solution; it simply passes the connection through. You are responsible for managing the WebSocket server, connection state, and scaling on your backend targets. ALB is better for containerized workloads or when you need more control over the WebSocket server implementation and can be more cost-effective at very high, sustained throughput.

• AWS AppSync: A fully managed GraphQL service that uses WebSockets for its real-time subscription feature. AppSync is a higher-level abstraction ideal for data-driven applications where clients need to subscribe to real-time updates when data changes in the backend. It has built-in broadcast capabilities and is often easier to use for pub/sub patterns compared to the manual connection management required by API Gateway. Choose API Gateway for more general-purpose, flexible, bidirectional messaging and AppSync for managed, real-time GraphQL APIs.

Exam Relevance

API Gateway WebSocket APIs are a key topic in several AWS certifications, particularly for developer and architect roles.

• AWS Certified Developer - Associate (DVA-C02): Expect questions on the basic architecture, the role of $connect, $disconnect, and custom routes, how to integrate with Lambda, and how to use the @connections URL to send messages back to clients. Questions may also cover securing the API with Lambda authorizers.
• AWS Certified Solutions Architect - Associate (SAA-C03): Questions will likely focus on use cases and architectural patterns. You should know when to choose a WebSocket API over a REST API and how it compares to alternatives like AWS AppSync or using an ALB for real-time communication.

Frequently Asked Questions

Q: How do I send a message from my backend to a specific connected client?

A: Your backend service (e.g., an AWS Lambda function) must make a POST request to the API Gateway Management API's callback URL. This URL has the format https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}. You must include the specific connectionId of the client you want to message. This is why it's essential to store the connectionId in a database when the client first connects.

Q: What is the difference between a WebSocket API and a REST API in API Gateway?

A: The primary difference is the communication model. A REST API uses a stateless, request-response pattern where the client sends a request and gets a response. A WebSocket API establishes a stateful, persistent connection, allowing for bidirectional, full-duplex communication where the server can push messages to the client at any time.

Q: How do I handle authentication and authorization for a WebSocket API?

A: Authentication is typically handled on the $connect route. You can use two main methods: AWS IAM, where requests are signed with AWS credentials, or a Lambda authorizer. A Lambda authorizer is a function that receives connection request details (like headers or query string parameters containing a JWT or API key) and returns an IAM policy indicating whether to allow or deny the connection.

---

This article reflects AWS features and pricing as of 2026. AWS services evolve rapidly — always verify against the official AWS documentation before making production decisions.