

Create a WebSocket API

Overview

A WebSocket API is a streaming API in WSO2 API Manager that is implemented based on the WebSocket protocol specification, which is compatible with HTTP. The WebSocket protocol supports full-duplex communication over a channel that is established once. Therefore, WebSocket protocols allow a continuous two-way communication between the server and the client.

You can create a WebSocket API from scratch in WSO2 API-M and export the WebSocket APIs that are created within WSO2 API-M as AsyncAPI definitions. Alternatively, you can also import existing AsyncAPI definitions to create SSE APIs in WSO2 API-M.

This section guides you through the process of creating a WebSocket API from scratch in which you can expose a WebSocket backend via WSO2 API Manager. After the API is created, you will be able to create independent channels to connect to each topic in the API. These topics can be mapped to different channels in the backend. As a result, the user can maintain multiple channels with the API to exchange different types of events simultaneously.

How it works

The WebSocket server can send messages to the WebSocket client, or vice-versa, or both. This is useful in use cases based on the Event Driven Architecture (EDA), where events are sent to be consumed in an asynchronous manner and paving the way for an immediate user experience.

Note

When you create a WebSocket Streaming API it's exposed via both ws and wss protocols. By default, the ws transport uses port 9099, and the wss transport uses port 8099.

Example usage

For example, chat room applications use WebSocket API so that messages can be sent in a bi-directional manner from the server to the client and vise versa.

Basic flow

Follow the instructions below to create a WebSocket API using the basic flow:

Step 1 - Design a WebSocket API

Defining port offset

If you apply a port offset to WSO2 API Manager, the Developer Portal UI will not get updated automatically.

Add the following configuration to explicitly configure port offset

1. Navigate to the deployment.toml file.

2. Add the following configuration.

    [[apim.gateway.environment]]
    ws_endpoint = "ws://localhost:9190"

   In the above configuration, the offset is 100. 9190 was obtained by adding 100 to the default port 9090.

1. Sign in to the Publisher.

   https://<hostname>:9443/publisher

   For testing purposes, you can use https://localhost:9443/publisher and admin as the username and password.

2. Click Create API, go to Streaming API, and Click WebSocket API.

   Note

   The Create button will only appear for a user who has the creator role permission.

   

3. Enter the API details.

   Field		Sample value
   Name		WebSocket
   Context		/websocket The API context is used by the Gateway to identify the API. Therefore, the API context must be unique. This context is the API's root context when invoking the API through the Gateway. You can define the API's version as a parameter of its context by adding the {version} into the context. For example, {version}/websocket. The WSO2 API-M assigns the actual version of the API to the {version} parameter internally. For example, ws://localhost:9099/1.0.0/websocket. Note that the version appears before the context, allowing you to group your APIs based on the versions.
   Version		1.0.0
   Protocol		WebSocket
   Endpoint		Use one of the following endpoints. ws://ws.ifelse.io:80 wss://ws.ifelse.io:443

   

4. Click Create to create the API.

   The overview page of the newly created API appears.

   

Step 2 - Configure the Topics

Topics of a WebSocket API are always Subscribe (sub) and Publish (pub), where the flow of events can be either from the server (backend) to the clients or from the client to the server. By default, the WebSocket API will have a topic with the name /*.

1. Click Topics under API Configurations and navigate to the Topics page.

2. Modify the topics as follows and click Save to update them.

   1. Optionally, click delete as shown below, to delete an existing topic.

      

   2. Select the Types, enter the Topic Name, and click + as shown below, to add a new topic.

      Topic Name

      /notifications

      

      The newly added topic is displayed as follows.

      

   3. Optionally, provide a URL Mapping to the topic.

      The provided URL Mapping will be appended to the WebSocket endpoint URL that you provided when creating the API, and the traffic via this topic will be sent to the resulting URL.

      Expand the created topic, provide a URL Mapping and click Save.

      Description	Chat room notifications
      URL Mapping	/notifications

      

Step 3 - View the AsyncAPI Definition

Click AsyncAPI Definition under API Configurations.

The AsyncAPI definition of the streaming API, which you just created, appears.

Now, you have successfully created and configured a Streaming API. Next, let's Publish your API.

End-to-end tutorial

Learn more by trying out an end-to-end tutorial on Creating and Publishing a WebSocket API, which uses the default Streaming Provider that works with WSO2 API Manager, namely the WSO2 Streaming Integrator.

Once you create and publish a WebSocket API, you can also deploy the API you created.

See Also

• Learn more on the concepts that you need to know when creating a Streaming API:

  • Endpoints
  • API Security
  • Rate Limiting
  • Life Cycle Management
  • API Monetization
  • API Visibility
  • API Documentation
  • Custom Properties

• Learn how to test a Streaming API. For an example, see Test a WebSub/WebHook API.

• Learn how to expose a stream as a managed API.

• Learn how you can use a third-party Streaming Provider.

Top