[Article] Introducing WebSocket APIs with WSO2 API Manager

Introduction

WSO2 API Manager is capable of handling many types of APIs efficiently. Because of the vast number of advantages it brings, many enterprises today are taking interest in the WebSocket protocol. With WSO2 API Manager 2.1.0 and future releases, users can expose their WebSocket services as APIs with OAuth 2.0 security, throttling capabilities and more.

What is WebSocket protocol?

WebSocket protocol is a popular protocol that gained its fame because it allows a long-held Transmission Control Protocol (TCP) socket connection to be established between the client and server. This allows bi-directional, full duplex messages to be instantly distributed with little overhead resulting in very low latency in connection.

This type of connection can be really useful in server push scenarios where the server notifies the client of updates. Usually, the client deals with this type of use case by sending a request and the server responding with the latest updates. When the WebSocket protocol is used, in this case, once the server has an update, the client can be notified instantly. Social feeds, stock market systems and Internet of Things (IoT) systems can be given as examples for this scenario.

Deployment architecture

Overview

Similar to other API types that WSO2 API Manager offers, WebSocket APIs also use Synapse for message mediation. The WSO2 API Manager uses the inbound endpoint artifact for this purpose. Inbound endpoints act as a listener and gives the ability to add a handler class to mediate the message flow.

Inbound endpoints

Inbound endpoints implement WebSockets via the Netty framework. Inbound endpoints give the ability to define a port on which to listen for a WebSocket connection and define a handler to mediate the WebSocket message flow. Inbound endpoints also give the capability to add a dispatch sequence and an out dispatch sequence.

• Dispatch sequence: After a WebSocket frame has gone through the Netty pipeline, the frame is dispatched to this sequence. The endpoint should be defined within this sequence.
• Out dispatch sequence: The WebSocket frames sent by the server to the client are sent to this sequence.

WebSocket API deployment

WSO2 API Manager has implemented a WebSocket duplex handler in the Netty pipeline to handle the OAuth, throttling and analytics functions. This handler can mediate both inbound and outbound WebSocket frames. For this, a WebSocket inbound handler and a WebSocket outbound handler have been implemented and defined within the WebSocket duplex handler. The WebSocket duplex handler diverts the message flow to the two handlers appropriately.

Once an API is published, a sequence is deployed for each environment defined with the endpoint configurations given in the API creation process.

Figure 1

Websocket API creation

WebSocket API creation can be done by filling out a form of three tabs: design, implement and manage. This process is similar to the creation of REST APIs, but differs due to the unavailability of resources for WebSocket APIs. The three tabs comprise of the following functions:

• Design: Add API name, context, version, and other basic info.
  • API Name: This is used to Identify each API. This field cannot be a duplicate value.
  • API Context: This is appended to the API invocation URL so that this specific API can be called. This field cannot be a duplicate value.
  • API Version: WebSocket APIs support versioning. This means that new versions of a WebSocket API can be created, updated or deleted. This field should be defined to assign a version number to a WebSocket API.
• Implement: Add the production and sandbox endpoint for the WebSocket API.
  • Production Endpoint: The actual endpoint for the WebSocket API should be defined here. Once the WebSocket API is invoked, the client will be directed to this endpoint.
  • Sandbox Endpoint: Unlike the production endpoint this endpoint is used as a pre-production environment that can be used in cases where a user needs a mock back-end system.
• Manage: Add throttling and set default API.
  • Default API: As mentioned above, WSO2 API Manager provides the ability to create multiple versions of WebSocket APIs. Out of these different versions, WSO2 API Manager has given the API Publisher the ability to define a default API version, so that if a user invokes an API without a version in the API invocation URL the user will be directed to this API.
  • Throttling: API Publisher gets the ability to select an API level throttling policy. These policies can be defined via the WSO2 API Manager admin console application.

Figure 2

WebSocket API invocation

Establish connection via handshake

In order to invoke a WebSocket API the user should have met the following requirements:

• A WebSocket client capable of adding headers to the WebSocket handshake request.
• A valid access token.

Figure 3

Then the user can invoke the API by calling the invocation URL given in the API overview of the WSO2 API Manager Store. The following headers are sent via the handshake request.

Sec-WebSocket-Key
The WebSocket handshake is done via the HTTP protocol. With the handshake request, a Sec-WebSocket-Key header is sent to the server. This header is used by the server to verify whether the handshake is actually initiated via a valid WebSocket client. Using this header the server can prevent non-WebSocket clients (e.g. HTTP clients) that are being abused to send data to unsuspecting WebSocket servers.

Sec-WebSocket-Version
The WebSocket protocol version that the client is trying to invoke the WebSocket API with is sent via this header. This is required by the server in processing the handshake. If the server does not support the WebSocket protocol version the client is trying to initiate, the server will respond with the versions supported by the server.

Authorization
This header should include the access token which should be obtained from the WSO2 API Manager via calling the token API. This is required to authorize the user via OAuth 2.0.

Once the server acknowledges the handshake it accepts the connection and sends a Sec-Websocket-Accept header informing the client that it is willing to initiate a WebSocket connection. The server also sends a connection and upgrade header that upgrades the existing HTTP connection with the server to a fully duplex WebSocket connection.

WebSocket frame communication

Once the handshake is completed, the client and server can communicate with each other by exchanging WebSocket frames. This allows the client to send a WebSocket frame to the server or the server to send a WebSocket frame to the client as intended unless a throttling policy has been violated.

WebSocket API throttling

Once the initial handshake is done, the communication in a WebSocket connection is done via WebSocket frames. Here, an API publisher or subscriber may come up with a need to limit the frames transferred either way to prevent exhausting resources. WSO2 API Manager gives the throttling capability for WebSocket APIs by limiting the frames transferred back and forth.

WSO2 API Manager allows throttling policies to be applied on the base of WebSocket frame count or bandwidth. It should also be noted that the frames will be throttled out once the aggregate amount of frames sent from the client to the backend and vice versa reach the defined amount specified in the throttling policy.

The throttling policies can be added for the following levels:

• Application level: This limit ensures the maximum number/size of frames that can be consumed by a single user of an application.
• Subscription level: This limit ensures the maximum number/size of frames that can be consumed by all users of the application against the subscribed API.
• API level: Throttle policies defined at this level are applied based on the metadata of the API that belongs to a particular API request. The purpose of having policies at this level is to limit the total number of requests coming to an API from any number of users from any number of applications.

WebSocket API analytics

A prominent need of an API publisher is API analytics. Analytics can be used to monitor the usage of the APIs and get a lot of other interesting information. Some of them are listed below:

• API usage
• API usage across geographical locations
• Top API users
• API throttled requests
• API last access times

WSO2 API Manager provides analytics for WebSocket APIs, but there are some facts to consider because this is a different scenario.

• Since WebSocket communication does not use the request-response pattern, each frame passed from one client to the server is considered as one request.
• The client should send relevant headers needed for analytics (e.g. X-forwarded-for) Else some analytics functionality may not function as expected.
• Some analytics information such as API latency and usage by resource path may not be available because they do not apply for the WebSocket protocol.

WebSocket APIs also support Google Analytics.

Conclusion

WebSocket APIs are becoming a need with the recent interest in exposing services via the WebSocket protocol. This article discussed different avenues of WSO2 API Manager WebSocket API implementation. By connecting to a WebSocket API, a user can access a fully duplex stream of WebSocket data exchange with the server. WSO2 API Manager provides OAuth security, throttling WebSocket frames, analytics and many other interesting capabilities for WebSocket APIs.