Skip to content

Add docs for asyncapi v3 #11005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NethmiRanasinghe wants to merge 1 commit into
base: 4.7.0
Choose a base branch
from
Open

Add docs for asyncapi v3 #11005

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 28 additions & 9 deletions ...ign-manage/design/create-api/create-streaming-api/create-a-sse-streaming-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,31 +110,50 @@ Follow the instructions below to create the API using the basic flow.

### Step 2 - Configure the Topics

Topics of an SSE API are always **Subscribe only**, where the flow of events will be from the server (backend) to the client. By default, an SSE API will have a topic with the name `/*`.
Topics of a SSE API are always **Receive only**, where the flow of events will be from the server (backend) to the client.

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

2. Modify the topics as follows and click **Save** to update them.
2. By default, the newly created SSE API will have a topic with the name `/*`.

1. Optionally, click delete, as shown below, to delete an existing topic.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-topics.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-topics.png" width="80%" alt="SSE API Topics Page"></a>

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-delete-default-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-delete-default-topic.png" width="80%" alt="SSE API Delete Existing Topic"></a>
3. This default channel `/*` will have a default operation `receive_/*`.

2. Select **sub** under **Types**, enter the **Topic Name**, and click **+** as shown below, to add a new topic.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-operation.png" width="80%" alt="SSE API Channel Operations"></a>

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-create-new-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-create-new-topic.png" width="80%" alt="SSE API Add Topic"></a>
4. Modify the topics as follows and click **Save** to update them.

The newly added topic is displayed as follows.
1. Optionally, click delete as shown below, to delete an existing topic or an operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-newly-added-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-newly-added-topic.png" width="80%" alt="SSE API Newly Added Topic"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-delete-default-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-delete-default-topic.png" width="80%" alt="SSE API Delete Existing Topic"></a>

2. Select **receive** under **Types**, enter the **Address** of the channel to be created, enter the **Operation Name** to be added to the selected channel, and click **+** as shown below, to add a new topic.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-create-new-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-create-new-topic.png" width="80%" alt="SSE API Add Topic"></a>

The newly added topic is displayed as follows. Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-newly-added-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-newly-added-topic.png" width="80%" alt="SSE API Newly Added Topic"></a>

3. You can also add a new operation to an existing topic by selecting the respective channel address from the dropdown.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-add-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-add-operation.png" width="80%" alt="SSE API Add Operation"></a>

Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-new-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-new-operation.png" width="80%" alt="SSE API Newly Added Operation"></a>

### Step 3 - View the AsyncAPI Definition

Click **AsyncAPI Definition** under **API Configurations**.

!!! note
The API definition will be generated in AsyncAPI V3.0.0.

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

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-asyncapi.png" width="80%" alt="SSE API AsyncAPI Definition"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/sse-api-v3-asyncapi.png" width="80%" alt="SSE API AsyncAPI Definition"></a>

### Step 4 - Configure the Runtime Configurations

Expand Down
14 changes: 10 additions & 4 deletions ...-api/create-streaming-api/create-a-streaming-api-from-an-asyncapi-definition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ Follow the instructions below to create a Streaming API using an AsyncAPI defini

<html><div class="admonition note">
<p class="admonition-title">Note</p>
<p>AsyncAPI import now supports both AsyncAPI v2 and AsyncAPI v3 definitions.</p>
<p>AsyncAPI import now supports both AsyncAPI v2.x and AsyncAPI v3.0 definitions.</p>
</div>
</html>

For this example, let's select **AsyncAPI File**, upload the following file, and click **Next**.

[Download AsyncAPI file]({{base_path}}/assets/attachments/103332601/streetlights_v3-def.yml)
[Download AsyncAPI V3 file]({{base_path}}/assets/attachments/103332601/streetlights_v3-def.yml)

<a href="{{base_path}}/assets/attachments/103332601/asyncv3-file.png"><img src="{{base_path}}/assets/attachments/103332601/asyncv3-file.png" width="80%" alt="Import Websocket Streaming API from AsyncAPI File"></a>

Expand Down Expand Up @@ -71,10 +71,14 @@ Follow the instructions below to create a Streaming API using an AsyncAPI defini

Click **Topics** to navigate to the topics page.

[![AsyncAPI topics]({{base_path}}/assets/attachments/103332601/asyncv3-topics-page.png)]({{base_path}}/assets/attachments/103332601/asyncv3-topics-page.png)
[![AsyncAPI topics]({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-topics.png)]({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-topics.png)

You will notice that the topics have been created automatically from the AsyncAPI definition specified in the provided URL.

[![AsyncAPI operations]({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-operations.png)]({{base_path}}/assets/img/design/create-api/streaming-api/asyncv3-operations.png)

Expand each topic to view the operations which are automatically created for each channel, as defined in the specification.

## Step 3 - View the AsyncAPI Definition

Click **AsyncAPI Definition** under **API Configurations**.
Expand All @@ -83,7 +87,9 @@ The AsyncAPI definition of the streaming API, which you just created, appears.

<a href="{{base_path}}/assets/attachments/103332601/asyncv3-def-view.png"><img src="{{base_path}}/assets/attachments/103332601/asyncv3-def-view.png" alt="WebSocket API AsyncAPI Definition"></a>

Now, you have successfully created a Streaming API from an Async API Definition.
Now, you have successfully created a Streaming API from an Async API Definition.

If you have created the streaming API using an AsyncAPI v2.x definition, see [AsyncAPI v2.x for APIM 4.6.0](https://apim.docs.wso2.com/en/latest/api-design-manage/design/create-api/create-streaming-api/create-a-streaming-api-from-an-asyncapi-definition/).

Next, publish the API, for more information, see [Publish an API]({{base_path}}/deploy-and-publish/publish-on-dev-portal/publish-an-api).

Expand Down
48 changes: 35 additions & 13 deletions ...nage/design/create-api/create-streaming-api/create-a-websocket-streaming-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,44 +129,66 @@ Follow the instructions below to create a WebSocket API using the basic flow:

### 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 `/*`.
Topics of a WebSocket API represents the channels which support actions **Receive and Send**, where the flow of events can be either from the server (backend) to the clients or from the client to the server.

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

2. By default, the newly created WebSocket API will have a topic with the name `/*`.

2. Modify the topics as follows and click **Save** to update them.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-topics.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-topics.png" width="80%" alt="WebSocket API Topics Page"></a>

1. Optionally, click delete as shown below, to delete an existing topic.
3. This default channel `/*` will have two default operations `send_/*` and `receive_/*` and are listed inside the respective action of the channel.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-delete-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-delete-topic.png" width="80%" alt="WebSocket API Delete Topic"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-operation.png" width="80%" alt="WebSocket API Channel Operations"></a>

2. Select the **Types**, enter the **Topic Name**, and click **+** as shown below, to add a new topic.
4. Modify the topics as follows and click **Save** to update them.

<table><tr><td>Topic Name</td><td><code>/notifications</code></td> </tr></table>
1. Optionally, click delete as shown below, to delete an existing topic or an operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-add-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-add-topic.png" width="80%" alt="WebSocket API Add Topic"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-delete-topic-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-delete-topic-operation.png" width="80%" alt="WebSocket API Delete Topic"></a>

The newly added topic is displayed as follows.
2. Select a **Type**, enter the **Address** of the channel to be created, enter the **Operation Name** to be added to the selected channel, and click **+** as shown below, to add a new topic.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-newly-added-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-newly-added-topic.png" width="80%" alt="WebSocket API Newly Added Topic"></a>
<table>
<tr><td>Channel Address</td><td><code>/notifications</code></td> </tr>
<tr><td>Operation Name</td><td><code>sendNotifications</code></td> </tr>
</table>

3. Optionally, provide a URL Mapping to the topic.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-channel.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-channel.png" width="80%" alt="WebSocket API Add Channel"></a>

The newly added topic is displayed as follows. Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-channel.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-channel.png" width="80%" alt="WebSocket API Newly Added Topic"></a>

3. You can also add a new operation to an existing topic by selecting the respective channel address from the dropdown.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-add-operation.png" width="80%" alt="WebSocket API Add Operation"></a>

Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-new-operation.png" width="80%" alt="WebSocket API Newly Added Operation"></a>

4. 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 **both** PUB and SUB under the created topic, provide the same URL Mapping for both and click **Save**.
Expand **both** SEND and RECEIVE under the created topic, provide the same URL Mapping for both and click **Save**.

<table><tr><td> Description</td> <td>Chat room notifications</td> </tr>
<tr><td>URL Mapping</td> <td><code>/notifications</code></td> </tr></table>

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/wesocket-streaming-api-v3-add-topic-url-mapping.png" width="80%" alt="WebSocket API Topic URL Mapping"></a>

### Step 3 - View the AsyncAPI Definition

Click **AsyncAPI Definition** under **API Configurations**.

!!! note
The API definition will be generated in AsyncAPI V3.0.0.

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

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-asyncapi.png" width="65%" alt="WebSocket API AsyncAPI Definition"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websocket-streaming-api-v3-asyncapi.png" width="65%" alt="WebSocket API AsyncAPI Definition"></a>

### Step 4 - Configure the Runtime Configurations

Expand Down
37 changes: 28 additions & 9 deletions ...-manage/design/create-api/create-streaming-api/create-a-websub-streaming-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,33 +73,52 @@ Follow the instructions below to create a WebHook API using the basic flow:

### Step 2 - Configure the Topics

Topics of a WebSub/Webhook API are always **Subscribe only**. By default, a WebSub/Webhook API will have a topic with the name `_default`.
Topics of a WebSub/Webhook API are always **Receive only**.

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

2. Modify the topics as follows and click **Save** to update them.
2. By default, the newly created WebSub/Webhook API will have a topic with the name `_default`.

1. Optionally, click delete, as shown below, to delete an existing topic.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-topics.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-topics.png" width="80%" alt="websub API Topics Page"></a>

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-delete-default-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-delete-default-topic.png" width="80%" alt="WebSub API Delete Existing Topic"></a>
3. This default channel `_default` will have a default operation `receive__edfault`.

2. Select **sub** under **Types**, enter the **Topic Name**, and click **+** as shown below, to add a new topic.
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-operation.png" width="80%" alt="websub API Channel Operations"></a>

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-add-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-add-topic.png" width="80%" alt="WebSub API Add Topic"></a>
4. Modify the topics as follows and click **Save** to update them.

The newly added topic is displayed as follows.
1. Optionally, click delete as shown below, to delete an existing topic or an operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-newly-added-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-newly-added-topic.png" width="80%" alt="WebSub API Newly Added Topic"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-delete-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-delete-topic.png" width="80%" alt="WebSub API Delete Existing Topic"></a>

2. Select **receive** under **Types**, enter the **Address** of the channel to be created, enter the **Operation Name** to be added to the selected channel, and click **+** as shown below, to add a new topic.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-add-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-add-topic.png" width="80%" alt="WebSub API Add Topic"></a>

The newly added topic is displayed as follows. Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-newly-added-topic.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-newly-added-topic.png" width="80%" alt="WebSub API Newly Added Topic"></a>

Expand the created topic to view its **Callback URL**. You can use this when registering the topic with a WebHook provider (WebSub Provider).

3. You can also add a new operation to an existing topic by selecting the respective channel address from the dropdown.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-add-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-add-operation.png" width="80%" alt="WebSub API Add Operation"></a>

Expand the topic to view the newly added operation.

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-new-operation.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-new-operation.png" width="80%" alt="WebSub API Newly Added Operation"></a>

### Step 3 - View the AsyncAPI Definition

Click **AsyncAPI Definition** under **API Configurations**.

!!! note
The API definition will be generated in AsyncAPI V3.0.0.

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

<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-asyncapi.png" width="80%" alt="WebHook API AsyncAPI Definition"></a>
<a href="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-asyncapi.png"><img src="{{base_path}}/assets/img/design/create-api/streaming-api/websub-api-v3-asyncapi.png" width="80%" alt="WebHook API AsyncAPI Definition"></a>

### Step 4 - Configure the Runtime Configurations

Expand Down
Loading