API Management 5 min


Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
Websocket.org 1

The WSO2 API Manager allows you to manage, monitor and monetize APIs. Ofcourse the API Manager does much more than that especially with all of the advanced functionality packed into the product. Especially the last couple of versions have really been feature-packed. From advanced throttling to the possibility to expose a WebSocket backend as an API.

Yes, we said WebSocket! You are forgiven if a WebSocket does not directly ring a bell. In this blog we look into the specifics of this new capability in API Manager 2.1.0

Websockets and WSO2 API Manager - lets get started

WebSockets and WSO2 API Manager

WebSocket is a protocol similar to HTTP (however, it’s only relationship to HTTP is that it’s handshake is interpreted by HTTP servers as an Upgrade request) and that it’s incorporated in the HTML5 specification. It enables simultaneous two-way (full-duplex) communication between the client and the server over a single connection. It is supported by almost all modern browsers.

The WebSocket protocol is designed to achieve the following:

  • Reduce unnecessary network traffic and latency
  • Allow streaming through proxies and firewalls while simultaneously supporting upstream and downstream communication
  • Be backward compatible with the pre-WebSocket world by starting up as an HTTP connection before switching to WebSocket frames

A WebSocket API in WSO2 API Manager allows an API creator to expose a WebSocket backend as an API to offer services via a WebSocket protocol while providing OAuth security, throttling, analytics, etc.

In other words, WebSockets are an additional format supported by the API Manager next to of course regular API’s (running locally or somewhere on the intranet or internet) and SOAP endpoints fronted by an API.

The WebSocket protocol specification defines ‘ws’ and ‘wss’ as two new uniform resource identifier (URI) schemes[4] that are used for plain- and TLS connections, respectively. Apart from the scheme name and fragment (# is not supported), the rest of the URI components are defined to use URI generic syntax.

Furthermore, communication is done over standard HTTP TCP port 80 (or 443 in the case of TLS-encrypted connections), which benefits those environments that block non-web Internet connections by a firewall.

An example of an API calling a websocket service

Much like the AXIS2 echo service that is included in the API Manager there is also a Websocket echo service that we can call. This service can be found at ws://echo.websocket.org/, this is the not secured variant as opposed to wss://echo.websocket.org/. You can try out the functionality of this simple service from the page of websockets.org

Websockets and WSO2 API Manager - websockets.org

Using the browser Developer Tools, developers can inspect the WebSocket handshake as well as the WebSocket frames.

Let’s start creating an API on the WSO2 API Manager to expose this test echo endpoint from websocket.org.

We start in the WSO2 API Publisher and start API Creation.

Creating an WebSocket API

Websockets and API Manager - Design API

Select the Production and Sandbox endpoints (in this case the echo service at websocket.org).

Pay attention to the protocol scheme used in the URL shown here. We need to use the websocket scheme for the endpoints.

Websockets and WSO2 API manager - EchoWebsocket

Click on Manage to finalize the creation of the API

Click on Save & Publish to Publish the API to make it available in the API Manager Store. As you have seen, defining  the API is very much like defining a regular API with some notable differences as far as the options available for selection like mediation etc that are not available. The webSocket API is a passthrough API and does not process the messages flowing through it.

Subscribing to the API

We are now  going  to subscribe to the API from the store. We will take the regular credentials (admin/admin)

Websockets and WSO2 API Manager - APIs

Create a new application for the subscription. You can of course also take an existing application but if you want to throw everything away afterwards this will be the cleanest way.

Websockets and WSO2 API Manager - Add Application

Subscribe to the API using the newly created application and the gold tier we defined earlier in the API Publisher.

Websockets and WSO2 API Manager - EchoWebSocket - v1.0

Click on subscribe to subscribe and View Subscriptions.

Websockets and WSO2 API Manager - Subscription Successful

Click on the EchoWebsocket-v1.0.

Websockets and WSO2 API Manager - WebSocketApplication

Note the endpoint being the websocket variant.

Websockets and WSO2 API Manager-EchoWebSockets - v1.0 endpoint

Now go to applications and select the WebSocketApplication.

Websockets and WSO2 API Manager - Application

Websockets and WSO2 API Manager - WebSocketApplication-2

Generate keys to get  a client ID, client Secret and Access token. We need to access token to test accessing the API. This token is unique for each user so the value shown in the image below will differ from your token! Note the token and copy it to the clipboard.

Websockets and WSO2 API Manager - Generate a test token

Accessing the service

As you might have seen, there is no Try-it functionality. What we need do is to download a sample client in Java, make changes so it uses the API we just created and the access token we just generated.

After the download from: https://docs.wso2.com/download/attachments/57748790/sample-ws-client.zip?version=2&modificationDate=1484568275000&api=v2 unzip the file to a directory.

Fire up your favorite IDE so you can edit the source code. We’ll use Eclipse for this blog.

Import the client from an Existing Maven Project.

Websockets and wso2 api manager - import existing maven project

Point to the sample-ws-client directory and import all. You will end  up with something like this:

websockets and wso2 api manager - sample-ws-client

The main class which we have to change is the WebSocketClient class. The first thing we need to do is to actually see if the URL is correct.

This is not the case as you can see:

websockets and wso2 api manager - no correct url.png

We change it to the URL exposed through our WSO2 API Manager, this URL was shown in the API Store as shown previously. Mind the port number being 9099 as the websockets port.

websockets and wso2 api manager - url exposed through wso2 api manager

Since localhost will often be defined on your machine the localhost will work but since we have a version v1.0 rather than 1.0 we need to change it as well.

Our client also needs the access token so we copy that as well to the WebSocketClient:

websockets and wso2 api manager - access token

Save the changes to the file and  start the WebSocket Client using Run As:

websockets and wso2 api manager - start websocket client

If everything is correct you will get a message “WebSocket Client connected!” and you can send a message to the Echo service like : Hello WebSocket World

websocket and wso2 api manager - websocket client connected.pngwebsocket and wso2 api manager - websocket client connected.png

With this example we have shown that we can actually create an API to a websocket backend.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product SupportWSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.

Full API lifecycle Management Selection Guide


smartmockups l0qqucke