In Part 2, we looked at HTTP and REST APIs. These are known as stateless APIs. You (the client) ask a question, the server gives an answer, and then the server immediately forgets about you. If you want another update, you have to ask again.
But what if you are building a chat application, a live stock ticker, or a multiplayer game? You can't have your app asking the server "Any new messages?" every single second—it would drain the user's battery and crash your server.
You need the server to say, "Hey, don't keep asking. Just stay on the line, and I will push the new messages to you the second they arrive."
This is where Amazon API Gateway WebSocket APIs come in.
What is a WebSocket API?
Unlike a standard REST API, a WebSocket API is stateful and bidirectional .
Think of a REST API like sending a text message: You send a text, wait, and get a reply.
Think of a WebSocket API like a phone call: You dial the number, someone picks up, and the line stays open. Both of you can talk and listen at the exact same time without having to hang up and redial .
In API Gateway, a WebSocket API creates a persistent connection between your user's app and your AWS backend . The backend can now independently push data down to the client without the client explicitly requesting it .
How Do WebSockets Work in API Gateway?
Because the connection stays open, API Gateway needs a way to figure out what to do with the continuous stream of messages flowing back and forth. It does this using Routes .
When you build an HTTP API, you use URLs (like /get-weather or /update-profile) to tell the server what you want. But in a WebSocket, there is only one URL. Once you are connected, everything happens over that single open connection.
So, how does the server know if a message is a "chat message" or a "friend request"? API Gateway looks inside the actual content of the message using something called a Route Selection Expression.
If your app sends a JSON message like this:
{
"action": "send_message",
"text": "Hello World!"
}
API Gateway can look at the "action" property . It sees "send_message" and routes that specific chunk of data to the correct AWS Lambda function .
The Three Magical Predefined Routes
When you set up a WebSocket API, AWS gives you three built-in routes to manage the lifecycle of the phone call :
$connect: This triggers the exact moment a user opens the app and connects to the API . You usually connect this to a Lambda function that saves the user's unique "Connection ID" into a database (like DynamoDB) so you know who is online.
$disconnect: This triggers when the user closes the app or loses their internet connection . You use this to delete their Connection ID from your database.
$default: If the user sends a message that doesn't match any of your custom rules, it falls into this bucket . It is a great place to send error messages like "Sorry, I didn't understand that command."
How the Server Talks Back
Getting messages from the user is easy, but how does the server push messages back to them?
Because you saved the user's "Connection ID" during the $connect phase, your backend services (like Lambda) can use a special AWS command called the @connections API .
If User A sends a chat message intended for User B, your Lambda function looks up User B's Connection ID in your database. It then uses the @connections API to push the text directly to User B's open WebSocket .
Important Limitations to Keep in Mind
WebSockets are powerful, but they aren't magic. AWS enforces a few rules you need to know:
Idle Timeouts: If a user connects but doesn't send or receive any data for 10 minutes, API Gateway will automatically hang up the phone (closing the connection with a 1001 status code) .
Maximum Lifespan: Even if the user is actively chatting, AWS forces a hard reset after 2 hours . Your app needs to be programmed to quietly reconnect when this happens.
Payload Limits: If a user tries to send a message that is too massive, API Gateway will reject it with a 1009 status code .
What's Next in the Series?
Now you know how to build fast HTTP APIs and real-time WebSocket APIs. But so far, we have left the front door completely unlocked. Anyone on the internet can access your endpoints, which could cost you a fortune or expose your data.
In Part 4: Securing & Throttling Your APIs, we are going to lock things down. We will look at how to use IAM, Lambda Authorizers, and Amazon Cognito to ensure only the right people get through the door, and how to use Quotas so they don't overwhelm your servers.
