WebSocket APIs in Amazon API Gateway – Push notifications

Starting from December 2018, Amazon Web Services (AWS) launched a widely-requested feature: WebSocket in Amazon API Gateway. With WebSocket available in AWS API Gateway, we are able to create client-driven, real-time applications which use a two-way/bidirectional communication (this means that a client can send messages to service and services can independently send messages to its clients). It is an advanced technology that makes it possible to open an interactive communication session between the user’s browser and a server.

WebSocket APIs are often used in real-time applications such as chat applications, collaboration platforms, multiplayer games, and financial trading platforms.

But before we dive into the how-to, there are some concepts that I want you to be aware of.

WebSocket API Gateway Concepts

Routes

$default route – if the route selection expression cannot be evaluated against the message or if no matching route is found.

$connect route – when a persistent connection between the client and a WebSocket API is being initiated.

$disconnect route – when the client or the server disconnects from the API.

$custom route –Â API Gateway calls a custom route, after the route selection expression is evaluated against the message, if a matching route is found the match determines which integration is invoked.Â

Route selection expression

A route selection expression is evaluated when the service is selecting the route to follow for an incoming message. The service will use the route whose routeKey exactly matches the evaluated value. If none match, and a route with the $default route key exists, that will be selected. If no routes match the evaluated value and there is no $default route, the service will return an error. For WebSocket-based APIs, the expression should be of the form $request.body.{path_to_body_element}.

Web Sockets are always useful in web applications. One tutorial, that I find quite interesting, demonstrates Chat based on the API Gateway Web Sockets. You can find the link in the References section. The client sends a message and it is fan-out to the connected client.

In addition, I will initiate a push message from â€śexternalâ€ť logic, i.e. another Lambda function which will have a timed trigger. When you invoke that Lambda function, it will send a message to the specifically connected client (even if none of the connected clients has sent a message).

This means I will create a Lambda function which will send a message to the connected client, relation: server -> client.

How-to

This is an addition to the Chat application showed in the tutorial above.

(Go to IAM Console -> Choose â€śRolesâ€ť from the left vertical menu -> Click on â€śCreate roleâ€ť -> Select â€śAWS serviceâ€ť from â€śSelect type of trusted entityâ€ť -> Then choose â€śLambdaâ€ť as a service that will use this role -> Search for â€śAPIGatewayAdminitratorâ€ť -> Choose â€śAmazonAPIGatewayAdministratorâ€ť -> optional: Insert Tags -> Give a name for the role -> Create role )

(Now when you have a role go to the Lambda function creation and choose your created role)

Conclusion

In this post, I explained a little bit about WebSocket API, including WebSocket in API Gateway. Additionally,Â below you can find the link with a full tutorial about using and creating a real chat application with WebSocket plus creating a PUSH notification with Lambda function that will send a message to connected clients.