Deploying a WebSocket API in Choreo Connect¶
You can deploy a WebSocket API in the following ways depending on the Choreo Connect mode you have chosen.
|Choreo Connect with WSO2 API Manager as a Control Plane||Via WSO2 API Manager Publisher Portal|
|Choreo Connect as a Standalone Gateway||Via apictl for Standalone Mode|
Characteristics of WebSocket APIs Deployed in Choreo Connect
- The API is created based on the Channels defined in the AsyncAPI definition. They are also known as Topics in WSO2 API Manager, and have a slight similarity to Resources in a REST API.
- Once the API is exposed, although the Gateway endpoint includes a basepath (with topic paths if defined), the Connection Request will be sent to the original backend endpoint you provided without any appended paths.
- If you have a requirement to append different paths to the backend URL for different Channels (Topics), a URL-mapping can be added. The Topics that do not include a URL-mapping will have the usual behavior as mentioned above.
- WebSocket APIs support OAuth 2.0 Security and each Topic can have its own local scope.
- If configured, Choreo Connect is also capable of publishing analytics for WebSocket frames sent and received by the client.
- Pub is prioritized over Sub. Currently, properties such as URL Mapping and Security are supported at Pub/Sub level rather than per topic (similar to REST APIs). Therefore, in WebSocket APIs, these must be defined under Publish or Subscribe. Yet, from a Gateway point of view, both Publish and Subscribe are initiated with a GET request that appears the same. Hence, if a Topic has both Publish and Subscribe, the properties for Publish will be prioritized.
Via WSO2 API Manager Publisher Portal¶
Follow the instructions below to deploy a WebSocket type Streaming API to Choreo Connect via the Publisher Portal in WSO2 API Manager. The Publisher Portal provides the capability to conveniently add and update the following.
- The AsyncAPI definition
- Rate limiting policies
- Security scopes
- URL mappings
Before you begin
This guide assumes that you already have a Choreo Connect instance configured to run with API Manager. If not, checkout the Quick Start Guide on how to install and run Choreo Connect. To learn more about Choreo Connect, have a look at the Overview of Choreo Connect.
Step 1 - Create a WebSocket API in API Manager¶
Create a WebSocket API by following the steps in Create a WebSocket API.
By default, a WebSocket API is protected by OAuth2 in Choreo Connect. Make sure to switch on security for the API via Publisher and Save.
Step 2 - Deploy and publish the API¶
- Deploy the API in Choreo Connect by navigating to the Deployments page from the left menu. For more information, see Deploy API.
- Publish the API from the Lifecycle page.
Step 3 - Generate an Access Token to invoke the API¶
To generate a temporary test key to invoke the API, follow the steps here
Click View in Dev Portal at the top right corner to open Developer Portal in another browser tab.
Open Applications from the top menu and select DefaultApplication from the list.
Open the Subscriptions tab and subscribe your API to the DefaultApplication.
Open APIs from the top menu and select your API.
Open the Subscriptions tab from the left menu bar, click on PROD KEYS, and generate keys.
Open the Try Out tab and click GET TEST KEY. This will include the access token in the cURL command you generate in the section below.
Step 4 - Invoke the API using a WebSocket client¶
The WebSocket API exposed via Choreo Connect can be invoked using a WebSocket client.
Install wscat client.
From Developer Portal resource tab open the topic
/notificationsand generate the cURL command.
Open a command-line interface and run the cURL command.
Once connected, type anything you want. The websocket server you are connected to must echo back what you type.
Choreo Connect handles websocket connections via the same ports used for HTTP (9090) and HTTPS (9095).
Via apictl for Standalone Mode¶
The CLI tool (apictl) does not support initializing projects for Streaming APIs yet. However, you can download the sample WebSocket API project from here and try it out by deploying it to Choreo Connect. When you are using your own WebSocket API with Choreo Connect, you can change the relevant attribute values in
definitions/asyncapi.yaml files. There is an explanation regarding those attribute values here.
Below steps explain how to try out WebSocket API in Choreo Connect standalone mode using the above project.
Step 1 - Download the API¶
Download the sample WebSocket API in here. The WebSocket API project should adhere to the below file structure.
. ├── Definitions │ └── asyncapi.yaml └── api.yaml
Step 2 - Add a Choreo Connect Environment to apictl¶
Start the Choreo Connect in stand alone mode.
Download the CLI tool (apictl) and add Choreo Connect environment to it using the below command. This environment will hold the adapter URL for further commands
mgin the below command. The apictl commands that starts as
apictl mgare Choreo Connect specific. If a command does not have
apictlthen the command could probably be common to both Choreo Connect and API Manager, but it could also be API Manager specific.
The apictl commands here onwards are executed with the -k flag to avoid SSL verification with the Choreo Connect.
To communicate via HTTPS without skipping SSL verification (without -k flag), add the cert in the Choreo Connect truststore into the
apictl mg add env dev --adapter https://localhost:9843
Step 3 - Log in to the Choreo Connect Environment in apictl¶
Use the following command to log in to the above Choreo Connect cluster (in other words log in to the Choreo Connect adapter). When you log in, an access token will be retrieved from Choreo Connect and it will be saved in the apictl.
apictl mg login dev -u <username> -p <password> -k
apictl mg login dev -u admin -p admin -k
Step 5 - Deploy the API¶
Deploy the above WebSocket API to Choreo Connect by executing the following command.
apictl mg deploy api -f <path_to_the_WebSocket_API_project> -e dev -k
Step 5 - Generate an access token¶
The following command generates a JWT to test the API, and sets it to the variable called
TOKEN=$(curl -X POST "https://<hostname>:<port>/testkey" -d "scope=<scope values>" -H "Authorization: Basic base64(username:password)" -k -v)
TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)
Step 6 - Invoke the API¶
Install wscat client.
Invoke the API using the following command.
wscat -c 'ws://localhost:9090/websocket/1.0.0/notifications' -H "Authorization:Bearer $TOKEN"
Once connected, type anything you want. The websocket server will echo back what you type.