Streaming API Support with WSO2 API Manager

New open-source WSO2 API Manager release enables EDA deployments with industry-first full AsyncAPI spec support, streaming APIs and integrations, and webhook APIs; includes all WSO2 Enterprise Integrator functionality; and adds Service Catalog and API Revisioning.

Competition for customer loyalty, a desire for new revenue streams, and demand for supply chain resiliency are just three of the drivers behind enterprises accelerating their digital initiatives. APIs now serve as the primary building blocks for these efforts—assembling data, events, and services from within the organization, throughout ecosystems, and across devices. But integrated legacy systems and support for new event-driven architectures also play critical roles in enabling timely, meaningful digital interactions in response to customer actions. To support these demands, WSO2 has added significant new capabilities to WSO2 API Manager.

1. Introduction

As a global leader in the API management industry, WSO2 API Manager has been further enhanced with the capabilities needed to future-proof API-led integration businesses. The latest iteration (API Manager 4.0) comprises a host of features that can be used to reap the benefits of rapid digital transformation.

In addition to REST/SOAP compatibility, WSO2 API Manager 4.0 now offers first-class support for streaming APIs. Now, it is possible to expose an event stream as a managed API with all the necessary Quality of Services (QoS), such as applying security, rate-limiting, and analytics.

REST APIs have been the backbone of the modern technological ecosystem for quite some time, as they deliver benefits such as simplicity (a relatively easier learning curve) and unambiguity (provided with HTTP verbs such as GET and POST). However, owing to growing digital demands from consumers, real-time or instant applications have become commonplace. Whether it is a simple notification on a social media platform or a crucial stock price change to capitalize on, real-time information has become a necessity.

Streaming APIs come to the picture with this specific requirement as they enable near real-time communication from server to client without a hassle. Traditionally, REST APIs use polling (client requests server periodically in order to retrieve updates), which can be less reactive and significantly inefficient as it is highly resource-intensive, even when there are no considerable updates from the server.

Streaming APIs are used within an event-driven architecture (EDA) in order to support real-time/near real-time experiences. Applications or servers that produce events, publish those events to certain topics. The clients who are interested in the specific type of events subscribe to the topic(s) corresponding to those events, which enables them to receive events as they are published to the topics without separately sending a request.

2. REST vs. Streaming APIs

If we consider a more comprehensive comparison between REST and streaming APIs, streaming APIs accommodate an asynchronous server/client relationship, where the server pushes information to the client, rather than the conventional synchronous request/response cycle where the client sends a blocking request to the server and waits for the response. Moreover, streaming APIs have the capability to send multiple responses from the server to the client against the single request/single response cycle in REST APIs. There are several protocols that could be used in streaming APIs such as WebSockets, WebSub/WebHooks, and Server-Sent Events (SSE), where most of these protocols support HTTP to initiate the connection between server and client.

HTTP verbs (GET, POST, PUT, etc.) in REST APIs are comparable to publishing and subscribing in streaming APIs. Streaming APIs require an event backbone such as Kafka, RabbitMQ, etc. – where the server publishes information/event to a certain topic in the event backbone and the client who is interested in that particular information is subscribed to the topic. Therefore, topics serve somewhat of a similar purpose as the resources in REST APIs in distinguishing the requirement of the connection. For instance, let’s say ‘/orders’ resource in a REST API yields the information of the orders that have been placed in a store. Likewise, if we consider a streaming API, the topic ‘orders’ could be used to keep track of all the orders as they are made. The server publishes the order information as soon as an order is placed and the clients who are subscribed to the topic ‘orders’ receive the information of the order as soon as it is placed.

The AsynAPI specification is used to standardize the streaming APIs (EDAs) with the capability to document protocol-agnostic data of the API, such as message brokers, topics, event semantics, and authentication schemes. Similar to the Open API specification (aka swagger files) in REST APIs, Async APIs support both YAML and JSON formats. You can learn more about the AsyncAPI specification here.

3. Streaming APIs in WSO2 API Manager

WSO2 API Manager 4.0 enables users to create, publish, and manage streaming APIs seamlessly. There are two ways to consume a streaming API for a user. They are subscribing to a topic in an API to receive a stream of events upon the initialization of the connection between client and server and publishing an event stream to the server. Even though the common scenario would be the subscription to a topic to receive event streams, publishing is also possible.

Figure 1: High level representation of a streaming API

The topics in the streaming APIs can be mapped to an event backbone topic/queue such as Kafka, RabbitMQ, MQTT or JMS or to a streaming endpoint that is used to publish events such as WebSockets, gRPC, WebHooks, SSE or even a simple HTTP endpoint.

Figure 2: Topics in an event broker

Streaming APIs require a persistent connection between the client and the gateway. Hence, the channel is initiated from the server and the subsequent communication happens through the created connection. This persistent connection is mimicked by the protocols in order to reduce the overhead of keeping a persisted connection without a requirement, whereas this persistent connection helps to overcome the issue of creating an unnecessary amount of connections to maintain communication. WSO2 API Manager supports the following protocols for creating streaming APIs, where the publishers are allowed to maintain persistent connection channels with the subscribers. Let’s go through the architectural differences between each supported API types/protocols and their ideal use cases.

1. WebSockets

WebSockets is a full duplex, bi-directional protocol that communicates through a single Transfer Control Protocol (TCP) connection. They are more suitable for scenarios where there will be a substantial amount of messages communicated between the parties (which is an advantage since they support bi-directional communication unlike some of the other protocols used in streaming APIs). Moreover, WebSockets are HTTP compatible and run on ports 80/443. Most web browsers today support WebSockets.

Figure 3: Message flow (WebSockets)

2. Server-Sent Events (SSE)

Server-Sent Events (SSE) are suitable for scenarios where the client is subscribed to the server and the client requires to receive event streams without communicating with the server as the protocol is unidirectional. The client initiates the HTTP connection channel, where it is responsible for re-creating the connection in case it closes because of an error. The server is responsible for pushing asynchronous event streams to the channel and closing the connection if required.

Figure 4: Message flow (SSE)

3. WebHooks

WebHooks are more appropriate for use-cases such as firing notifications in contrast to an event (Slack, Google Calendar, Facebook, etc.). WSO2 API Manager has utilized the WebSub protocol to implement WebHook streaming APIs. WSO2 API Manager works as a low-scaled hub in the architecture, deviating it from a traditional WebSub message flow. The overall message flow for a client can be divided into two separate flows as the subscription flow and the response flow.

The subscription flow is the process of a client subscribing to a certain topic. The process can be broken down into the following steps.

• Initially the client sends the subscription request to the API gateway.
• Then, the gateway notifies the event hub about the subscription request and the event hub stores the subscription in the database for persistence.
• Thereafter, the event hub notifies all the gateways about the newly created subscription.

Figure 5: Subscription flow (WebHook)

Response flow is the process of delivering the event/notification to the subscribed clients. In the response flow:

• The event is initiated from the WebHook provider and it calls the gateway.
• The gateway publishes the event to the relevant clients who are subscribed to the topic.

The subscribers are fetched from the in-memory cache of the gateway, and, in case of a restart of the gateway, subscribers are fetched from the database through the event hub.

Figure 6: Response flow (WebHook)

All of the aforementioned protocols have been standardized by the World Wide Web Consortium (W3C).

4. Value addition with Streaming APIs

In order to utilize a streaming API in a modern-day practical scenario, a strong API management platform is required. This is to facilitate more advanced requirements such as security, throttling, monetization, and analytics since it is more challenging to accomplish these features for streaming APIs rather than for conventional REST APIs. WSO2 API Manager provides the ability to create a streaming API from scratch or use an existing AsyncAPI specification to create the API in the gateway and improve the quality of service. In addition to the substantial amount of features, the user/developer experience is of great importance since it makes the tasks more intuitive, ultimately providing new users an efficient platform to become familiarized with the system in a short period of time.

The following subsections will focus on the user experience aspects of API Manager 4.0 as well as the feature package.

Developer Experience

You have the capability to create streaming APIs from scratch as WebSocket, WebHook or SSE APIs and import an AsyncAPI definition to implement an already defined streaming API when using API Manager 4.0. An AsyncAPI specification will be generated for the APIs created from scratch. Learn about creating streaming APIs from our documentation.

Figure 7: Creator view of streaming APIs in publisher portal

Moreover, you can add the topics with the capability to publish/subscribe based on the streaming API created. (WebSocket protocol supports both publishing and subscribing since it is a bi-directional protocol whereas SSE and WebSub support only subscribing since they are uni-directional.)

Figure 8: Adding topics from publisher portal

Subscription policies can be created based on the number of events per unit time for all the streaming APIs and the number of subscriptions per API for WebHook APIs.

Figure 9: Business plans for streaming APIs

As for API discovery, the developer portal provides a platform to view the streaming APIs along with the available channels and details of them where clients can subscribe to their desired APIs.

Figure 10: API view of a streaming API in developer portal

API analytics is a crucial part of API management since it helps to monitor the usage and behavioral patterns of clients and the APIs. Since streaming APIs differ from traditional REST API, new metrics are required to get a view of the bigger picture such as the number of active connections, number of events fired, etc.

Figure 11: Event summary of streaming APIs (Analytics)

Features

The following subsections give an insight of how the aforementioned features are provided for streaming APIs comparatively to REST APIs.

1. Security

API security is one of the key aspects in an API management platform and API security can be categorized into two segments: authentication and authorization. API authentication is the decision of letting a user access the resources whereas API authorization is the decision of letting a particular user to perform certain tasks in a resource. Learn more about API security from here.

Securing a streaming API is trickier than a REST API since streaming APIs do not possess resources where a usual access token-based authentication and authorization can be implemented. Streaming APIs revolve around topics and a persistent channel between the client and server. Therefore, the client does not often send requests to the server. Hence, it is required to authenticate the client and provide the necessary authorization when initiating the HTTP connection channel with the server.

WSO2 API Manager offers authentication schemes such as OAuth2, API keys, and basic authentication. Learn more about the authentication mechanisms in API Manager here.

Furthermore, API Manager supports fine-grained authorization, where you can limit access for certain users to access/receive updates from certain topics only based on OAuth2 scopes if required. Learn more about fine grained access control in API Manager here.

2. Throttling/Rate limiting

Throttling in APIs is essential for a number of reasons such as securing backend services from attacks like denial of service (DoS), regulating traffic according to the availability of the services and monetization purposes. Throttling policies for REST/SOAP APIs is primarily based on the number of requests per unit time for a resource or the bandwidth for a resource. Since both of them are reliant on client interactions, a different approach is required. Streaming API throttling policies are based on the following:

1. Count-based throttling

• The connection is upheld until a certain number of events are received from an application/client.

2. Time-based throttling

• The connection is upheld until a predefined amount of time.

* Note - A hybrid throttling policy could be implemented combining the count based throttling and time based throttling to create policies which limit the number of events received by the application in a predefined time frame.

Throttling is implemented using different methods in different protocols of streaming APIs. WebSocket API throttling is implemented using the count of the websocket frames used for communication via the channel. The connection is throttled out when the aggregate amount of frames from client to server and server to client reaches the defined policy. SSE throttling is implemented using the count of events delimited by ‘\n\n’ characters and when the limit of events is reached the connection is throttled. WebSub(WebHook) throttling is implemented using the number of active connections and the number of events consumed in a given time unit.

Learn more about throttling of streaming APIs here.

3. Analytics

API Analytics play a vital role when taking business decisions in an organization since they provide an insight on the implemented APIs. Streaming API analytics differ from REST API analytics because of their architectural difference. The following indications of streaming APIs are used in generating a comprehensive analytical report in API Manager.

1. Event details (Success/Failure report)
2. API/Resource Usage details
3. Error count (Authentication errors, Target connectivity errors, Throttling errors, etc.)
4. Caching details
5. Device details

Figure 12: Error summary of streaming APIs (Analytics)

Learn more about API Manager analytics here.

Along with these features WSO2 API Manager provides a solid platform to reap the benefits of streaming APIs for an organization.

5. Summary

Streaming APIs have been gaining popularity with the rise of real-time or near-real-time information in people’s daily lives. Therefore, an API management solution with the capability to manage streaming APIs along with more conventional REST, SOAP APIs provide a great value for an organization to expand their horizons. Moreover, you have the capability to select a more eligible protocol from WebSockets, SSE and WebSub to fulfill your ultimate business requirement.

You can get hands-on experience of streaming APIs through WSO2 API Manager by following the documentation as well. Also, learn more about WSO2 API Manager 4.0 here.