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
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
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
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.
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)
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.
Subscribe to the API using the newly created application and the gold tier we defined earlier in the API Publisher.
Click on subscribe to subscribe and View Subscriptions.
Click on the EchoWebsocket-v1.0.
Note the endpoint being the websocket variant.
Now go to applications and select the WebSocketApplication.
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.
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.
Point to the sample-ws-client directory and import all. You will end up with something like this:
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:
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.
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:
Save the changes to the file and start the WebSocket Client using Run As:
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
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 Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
