Create a WebSocket API

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

A WebSocket API 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 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.

1. Sign in to the API Publisher.
   https://<hostname>:9443/publisher (e.g.  https://localhost:9443/publisher ). Use admin as the username and password.
2. In the APIS menu, click Add New API. 
   
3. Select the option to design a new WebSocket API and click Start Creating.
   

4. The Design tab of the API opens. Give the information in the table below and click Next: Implement > to proceed to the implementation phase.

   Field	Sample value
   Name	EchoWebSocket
   Context	/echowebsocket
   Version	1.0

   

5. Click the Managed API option.

6. Provide the production endpoint and sandbox endpoint, which is ws://echo.websocket.org:80 in 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.

   

7. 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.

8. When prompted, choose to open the newly published API in the API Store.
9. The EchoWebSocket API opens. Select an application (e.g., DefaultApplication), the Gold tier and subscribe to the API.
   

10. Click the View Subscriptions button when prompted. The Subscriptions tab opens.

11. 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. 

12. 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.

13. In this example, make sure that the URL in the sample-ws-client/src/main/java/io/netty/example/http/websocketx/client/WebSocketClient.java file matches the one in the API Store.
    
14. In the same file, copy and paste the Authorization Bearer access token you generated in step 11 as shown below.
    
15. Save your changes.
16. Open the sample-ws-client directory you downloaded in step 11 using an IDE. This tutorial uses IntelliJ Idea 15 CE as the IDE.
17. Run the WebSocket client as shown below.
    
18. Type a message in the WebSocket client and you will see that it echoes the message as intended by the WebSocket API. 
    

WSS Support

The instructions below show you how to use the WSS support capabilities in WSO2 API Manager.

1. Download the SecureWebSocketInboundEndpoint.xml and copy it to the <API-M_HOME>/repository/deployment/server/synapse-configs/default/inbound-endpoints/ directory.
2. Create a temporary patch named 'patch8888' directory inside <API-M_HOME>/repository/components/patches/. Download the org.wso2.carbon.websocket.transport-4.6.10.jar and copy it to the patch8888 directory.

3. Open the <API-M_HOME>/repository/conf/axis2/axis2.xml file. Copy the transport sender for websocket to the axis2.xml file. The code block sample is given below.

   <transportSender name="wss" class="org.wso2.carbon.websocket.transport.WebsocketTransportSender">
           <parameter name="ws.outflow.dispatch.sequence" locked="false">outflowDispatchSeq</parameter>
           <parameter name="ws.outflow.dispatch.fault.sequence" locked="false">outflowFaultSeq</parameter>
           <parameter name="ws.trust.store" locked="false">
               <ws.trust.store.location>repository/resources/security/client-truststore.jks</ws.trust.store.location>
               <ws.trust.store.Password>wso2carbon</ws.trust.store.Password>
           </parameter>
    </transportSender>

1. Create a WebSocket API using the endpoint wss://echo.websocket.org:443 as shown in the instructions above.
2. Download and unzip the sample-ws-client.zip to 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.
3. Open this source code in <WS_CLIENT_HOME> from your preferred Java IDE. Find the WebSocketClient.java class.
4. In addition to the changes mentioned in steps 13 and 14 given above, change the variable carbonKeyStoreLocation to point to <API-M_HOME>/repository/resources/security/wso2carbon.jks. Note that port for the WSS API is 8099.
5. Run the WSS client. You will see it connecting via the WSS API to the backend.