Extensible Architecture for Federated WebSocket API Discovery

[JaninduRSD]

Problem

What is the problem we are trying to solve?
The current Federated Gateway implementation in WSO2 API Manager is designed primarily for REST/HTTP APIs. This creates significant gaps in our multi-gateway strategy:

1. Discovery Gap: Users operating in a multi-gateway environment (Azure, Kong, etc.) cannot discover or onboard WebSocket APIs into the WSO2 Control Plane.
2. Process Failure: When the system attempts to discover WebSocket APIs, it incorrectly routes them through the existing REST onboarding flow. This results in parsing errors and causes the import process to fail completely.
3. Architectural Rigidity (Non-Extensible): The current Federated discovery architecture is tightly coupled to REST logic. Adding support for new API types is expensive, as the system lacks an extensible design pattern to easily plug in new protocols without modifying the core kernel.

Why should it be solved?

• Unified Governance: Organizations need a "Single Pane of Glass" to manage all their APIs regardless of protocol (REST vs. WebSocket) or deployment location (WSO2 Gateway vs. Azure/Kong).
• Architectural Extensibility: Moving to an extensible design (Factory & Strategy patterns) eliminates the high cost and risk of adding new protocols. This ensures the platform can easily scale to support diverse API types (like GraphQL or gRPC) without destabilizing the core kernel.

Who are we solving the problem for?

• API Product Managers: Streamlines the publication and management of WebSocket APIs deployed on external gateways.
• System Administrators: Provides an automated, error-free discovery cycle capable of handling diverse protocols without manual intervention.
• Application Developers: Establishes a centralized catalog where real-time and streaming APIs can be discovered and consumed alongside standard REST APIs.

Proposed Solution

The proposed architecture introduces a dynamic, plugin-based pipeline designed to discover, standardize, and govern APIs from external cloud providers (e.g., Azure, Kong) within the WSO2 ecosystem. The solution is structured into two primary phases: Dynamic Construction and Lifecycle Processing.

We introduce a three-layer abstraction (Base, Gateway-Specific, Type-Specific) to maximize code reuse. Common logic resides in the base, while specific implementations handle protocol nuances.

Phase 1: Dynamic API Standardization

To handle diverse data structures from external providers, the architecture employs a Dynamic Builder Factory that intelligently routes raw metadata to specialized processing tracks.

• Process Flow: Data flows through Protocol-Specific Mappers and a Shared Gateway Layer. Common configurations are handled in the Shared Layer, while specific implementations (e.g., WebSocket topics) are handled by the mappers.
• Design Patterns:
  • Factory Pattern: Dynamically instantiates the correct builder at runtime.
  • Template Method Pattern: Enforces a standard construction algorithm while delegating protocol-specific details to subclasses.

Phase 2: Handle Definitions On-Demand

A critical challenge in federated discovery is abstracting API definition operations (endpoint extraction, resource validation, artifact packaging) across diverse definition formats.

• Mechanism: We introduce a Dynamic Definition Handler Selector. When the Processing Engine requires technical details, it triggers this selector to dynamically pick the appropriate handler to extract the required data.
• Reuse: As shown in the architecture diagram, this same handler logic is reused by the Dev Portal to display endpoints to frontend users.
• Design Patterns:
  • Strategy Pattern: Defines a common interface for "Definition Handling," allowing the runtime to swap parsing strategies (OAS vs. AsyncAPI) seamlessly without modifying the core processing logic.

Alternatives

1. Status Quo (Hardcoded Logic)
Continuing to add if/else logic inside the main Discovery Agent to handle WebSockets.

• Why Rejected: This violates the Open/Closed Principle. It creates a monolithic, fragile codebase where adding future protocols (GraphQL, gRPC) becomes increasingly complex and error-prone.

2. Separate Discovery Agents per Protocol
Building a completely separate "WebSocket Discovery Agent" distinct from the REST agent.

• Why Rejected: This prevents Unified Governance. It creates silos where code for common tasks (Authentication, Organization Mapping) is duplicated, leading to higher maintenance costs.

Version

No response