WebSocket is a protocol similar to HTTP that is part of the HTML5 specification. It enables simultaneous two-way communication (full-duplex communication) between the client and the server over a single connection. 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
In this tutorial, you create and publish an API with a WebSocket backend and then invoke it using a Netty-based WebSocket client. You can use any WebSocket client to invoke the API.
- Sign in to the API Publisher.
adminas the username and password.
- In the APIS menu, click Add New API.
- Select the option to design a new WebSocket API and click Start Creating.
The Design tab of the API opens. Give the information in the table below and click Next: Implement > to proceed to the implementation phase.FieldSample value
Name EchoWebSocket Context
- Click the Managed API option.
Provide the production endpoint and sandbox endpoint, which is
ws://echo.websocket.org:80in this example, and click Next: Manage >.
With WSO2 API Manager, you can maintain a production and a sandbox endpoint for a given API. The production endpoint is the actual location of the API, whereas the sandbox endpoint points to its testing/pre-production environment.
The Test button for the production and sandbox endpoints does not work for WebSocket APIs and is a known issue.
In the Manage tab, select the Gold tier, scroll down and click Save & Publish.
For more information on API authentication (e.g., non authentic API invocation), see HTTP methods.
You have now published the WebSocket API to the API Store. Let's subscribe to it.
- When prompted, choose to open the newly published API in the API Store.
EchoWebSocketAPI opens. Select an application (e.g., DefaultApplication), the Gold tier and subscribe to the API.
Click the View Subscriptions button when prompted. The Subscriptions tab opens.
Click the Production Keys tab and click Generate Keys to create an application access token. If you have already generated keys before, click Regenerate.
You can also add a Callback URL, if you have not added it already when creating the API. You have now subscribed to an API in the API Store and can invoke it using a WebSocket client. In this tutorial, you invoke it using a Netty-based WebSocket client.
- In your client application, set the WebSocket API URL as shown in the API Store.
SDK generation is not supported for WebSocket APIs as they don't have swagger definitions.
- In this example, make sure that the URL in the
sample-ws-client/src/main/java/io/netty/example/http/websocketx/client/WebSocketClient.javafile matches the one in the API Store.
- In the same file, copy and paste the Authorization Bearer access token you generated in step 11 as shown below.
- Save your changes.
- Open the
sample-ws-clientdirectory you downloaded in step 11 using an IDE. This tutorial uses IntelliJ Idea 15 CE as the IDE.
- Run the WebSocket client as shown below.
- Type a message in the WebSocket client and you will see that it echoes the message as intended by the WebSocket API.
The instructions below show you how to use the WSS support capabilities in WSO2 API Manager.
- Create a WebSocket API using the endpoint
wss://echo.websocket.org:443as shown in the instructions above.
- Download and unzip the
sample-ws-client.zipto a directory to your local drive. This location will be referred to as
WS_CLIENT_HOME. This is a maven project of a simple WebSocket client.
- Open this source code in
<WS_CLIENT_HOME>from your preferred Java IDE. Find the
- In addition to the changes mentioned in steps 13 and 14 given above, change the variable
carbonKeyStoreLocationto point to
<API-M_HOME>/repository/resources/security/wso2carbon.jks. Note that port for the WSS API is 8099.
- Run the WSS client. You will see it connecting via the WSS API to the backend.