WebBroker API Management¶

Create a new WebBrokerAPI¶

POST /webbroker-apis

Code samples

curl -X POST http://localhost:9090/api/management/v0.9/webbroker-apis \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Add a new WebBrokerAPI to the Gateway. WebBrokerAPI provides bidirectional streaming between WebSocket clients and Kafka brokers with per-connection isolation.

Payload

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebBrokerApi",
  "metadata": {
    "name": "stock-trading-v1.0"
  },
  "spec": {
    "displayName": "Stock Trading WebBroker API",
    "version": "v1.0",
    "context": "/stock-trading/$version",
    "receiver": {
      "name": "websocket-receiver",
      "type": "websocket"
    },
    "broker": {
      "name": "kafka-driver",
      "type": "kafka",
      "properties": {
        "brokers": [
          "kafka-broker-1:9092",
          "kafka-broker-2:9092"
        ]
      }
    },
    "allChannels": {
      "on_connection_init": {
        "policies": []
      },
      "on_produce": {
        "policies": []
      },
      "on_consume": {
        "policies": []
      }
    },
    "channels": {
      "prices": {
        "produceTo": {
          "topic": "stock.prices"
        },
        "consumeFrom": {
          "topic": "stock.prices"
        },
        "on_connection_init": {
          "policies": []
        },
        "on_produce": {
          "policies": []
        },
        "on_consume": {
          "policies": []
        }
      }
    }
  }
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	WebBrokerApiRequest	true	none

Example responses

201 Response

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebBrokerApi",
  "metadata": {
    "name": "stock-trading-v1.0"
  },
  "spec": {
    "displayName": "Stock Trading WebBroker API",
    "version": "v1.0",
    "context": "/stock-trading/$version",
    "receiver": {
      "name": "websocket-receiver",
      "type": "websocket"
    },
    "broker": {
      "name": "kafka-driver",
      "type": "kafka",
      "properties": {
        "brokers": [
          "kafka-broker-1:9092",
          "kafka-broker-2:9092"
        ]
      }
    },
    "allChannels": {
      "on_connection_init": {
        "policies": []
      },
      "on_produce": {
        "policies": []
      },
      "on_consume": {
        "policies": []
      }
    },
    "channels": {
      "prices": {
        "produceTo": {
          "topic": "stock.prices"
        },
        "consumeFrom": {
          "topic": "stock.prices"
        },
        "on_connection_init": {
          "policies": []
        },
        "on_produce": {
          "policies": []
        },
        "on_consume": {
          "policies": []
        }
      }
    }
  },
  "status": {
    "id": "stock-trading-v1.0",
    "state": "deployed",
    "createdAt": "2026-04-24T07:21:13Z",
    "updatedAt": "2026-04-24T07:21:13Z",
    "deployedAt": "2026-04-24T07:21:13Z"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	WebBrokerAPI created successfully	WebBrokerApi
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
409	Conflict	Conflict - WebBroker API with same name and version already exists	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

List all WebBrokerAPIs¶

GET /webbroker-apis

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/webbroker-apis \
  -u {username}:{password} \
  -H 'Accept: application/json'

List WebBrokerAPIs registered in the Gateway, optionally filtered by name, version, or status.

Authentication¶

Parameters

Name	In	Type	Required	Description
displayName	query	string	false	Filter by WebBroker API display name
version	query	string	false	Filter by WebBroker API version
status	query	string	false	Filter by deployment status

Enumerated Values

Parameter	Value
status	deployed
status	undeployed

Example responses

200 Response

{
  "status": "success",
  "count": 3,
  "apis": [
    {
      "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
      "kind": "WebBrokerApi",
      "metadata": {
        "name": "stock-trading-v1.0"
      },
      "spec": {
        "displayName": "Stock Trading WebBroker API",
        "version": "v1.0",
        "context": "/stock-trading/$version",
        "receiver": {
          "name": "websocket-receiver",
          "type": "websocket"
        },
        "broker": {
          "name": "kafka-driver",
          "type": "kafka",
          "properties": {
            "brokers": [
              "kafka-broker-1:9092",
              "kafka-broker-2:9092"
            ]
          }
        },
        "allChannels": {
          "on_connection_init": {
            "policies": []
          },
          "on_produce": {
            "policies": []
          },
          "on_consume": {
            "policies": []
          }
        },
        "channels": {
          "prices": {
            "produceTo": {
              "topic": "stock.prices"
            },
            "consumeFrom": {
              "topic": "stock.prices"
            },
            "on_connection_init": {
              "policies": []
            },
            "on_produce": {
              "policies": []
            },
            "on_consume": {
              "policies": []
            }
          }
        }
      },
      "status": {
        "id": "stock-trading-v1.0",
        "state": "deployed",
        "createdAt": "2026-04-24T07:21:13Z",
        "updatedAt": "2026-04-24T07:21:13Z",
        "deployedAt": "2026-04-24T07:21:13Z"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	List of WebBrokerAPIs	Inline
500	Internal Server Error	Internal server error	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
status	string	false	none	none
count	integer	false	none	none
apis	[allOf]	false	none	none

allOf

Name	Type	Required	Restrictions	Description
anonymous	WebBrokerApiRequest	false	none	none
apiVersion	string	true	none	API specification version
kind	string	true	none	API type
metadata	Metadata	true	none	none
name	string	true	none	Unique handle for the resource
labels	object	false	none	Labels are key-value pairs for organizing and selecting APIs. Keys must not contain spaces.
additionalProperties	string	false	none	none
annotations	object	false	none	Annotations are arbitrary non-identifying metadata. Use domain-prefixed keys.
additionalProperties	string	false	none	none
spec	WebBrokerApiData	true	none	none
displayName	string	true	none	Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
version	string	true	none	Semantic version of the API
context	string	true	none	Base path for all API routes (must start with /, no trailing slash)
receiver	WebBrokerApiReceiver	true	none	WebSocket receiver configuration
name	string	true	none	Receiver name
type	string	true	none	Receiver type
properties	object	false	none	Additional receiver properties
broker	WebBrokerApiBroker	true	none	Message broker driver configuration
name	string	true	none	Broker driver name
type	string	true	none	Broker driver type
properties	object	true	none	Broker driver properties (e.g., bootstrap servers)
allChannels	WebBrokerApiAllChannelPolicies	false	none	Protocol mediation policies applied to all channels
on_connection_init	WebBrokerApiPolicyGroup	false	none	Group of policies
policies	[Policy]	false	none	List of policies to apply
name	string	true	none	Name of the policy
version	string	true	none	Version of the policy. Only major-only version is allowed (e.g., v0, v1). Full semantic version (e.g., v1.0.0) is not accepted and will be rejected. The Gateway Controller resolves the major version to the single matching full version installed in the gateway image.
executionCondition	string	false	none	Expression controlling conditional execution of the policy
params	object	false	none	Arbitrary parameters for the policy (free-form key/value structure)
on_produce	WebBrokerApiPolicyGroup	false	none	Group of policies
on_consume	WebBrokerApiPolicyGroup	false	none	Group of policies
channels	object	true	none	Map of WebSocket channels for bidirectional streaming with Kafka (key is channel name)
additionalProperties	WebBrokerApiChannel	false	none	WebSocket channel configuration with Kafka topic mapping
produceTo	WebBrokerApiProduceConfig	false	none	Configuration for producing messages from WebSocket to Kafka
topic	string	true	none	Kafka topic to produce messages to
consumeFrom	WebBrokerApiConsumeConfig	false	none	Configuration for consuming messages from Kafka to WebSocket
topic	string	true	none	Kafka topic to consume messages from
on_connection_init	WebBrokerApiPolicyGroup	false	none	Group of policies
on_produce	WebBrokerApiPolicyGroup	false	none	Group of policies
on_consume	WebBrokerApiPolicyGroup	false	none	Group of policies
vhosts	object	false	none	Custom virtual hosts/domains for the API
main	string	true	none	Custom virtual host/domain for production traffic
sandbox	string	false	none	Custom virtual host/domain for sandbox traffic
deploymentState	string	false	none	Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration and policies are preserved for potential redeployment.

and

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none
status	ResourceStatus	false	read-only	Server-managed lifecycle fields. Populated on responses.
id	string	false	none	Unique identifier assigned by the server (equal to metadata.name)
state	string	false	none	Desired deployment state reported by the server
createdAt	string(date-time)	false	none	Timestamp when the resource was first created (UTC)
updatedAt	string(date-time)	false	none	Timestamp when the resource was last updated (UTC)
deployedAt	string(date-time)	false	none	Timestamp when the resource was last deployed (omitted when undeployed)

Enumerated Values

Property	Value
apiVersion	gateway.api-platform.wso2.com/v1alpha1
kind	WebBrokerApi
deploymentState	deployed
deploymentState	undeployed
state	deployed
state	undeployed

Get WebBrokerAPI by id¶

GET /webbroker-apis/{id}

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/webbroker-apis/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Get a WebBrokerAPI by its ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier for the WebBroker API.

Detailed descriptions

id: Unique public identifier for the WebBroker API.

Example responses

200 Response

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebBrokerApi",
  "metadata": {
    "name": "stock-trading-v1.0"
  },
  "spec": {
    "displayName": "Stock Trading WebBroker API",
    "version": "v1.0",
    "context": "/stock-trading/$version",
    "receiver": {
      "name": "websocket-receiver",
      "type": "websocket"
    },
    "broker": {
      "name": "kafka-driver",
      "type": "kafka",
      "properties": {
        "brokers": [
          "kafka-broker-1:9092",
          "kafka-broker-2:9092"
        ]
      }
    },
    "allChannels": {
      "on_connection_init": {
        "policies": []
      },
      "on_produce": {
        "policies": []
      },
      "on_consume": {
        "policies": []
      }
    },
    "channels": {
      "prices": {
        "produceTo": {
          "topic": "stock.prices"
        },
        "consumeFrom": {
          "topic": "stock.prices"
        },
        "on_connection_init": {
          "policies": []
        },
        "on_produce": {
          "policies": []
        },
        "on_consume": {
          "policies": []
        }
      }
    }
  },
  "status": {
    "id": "stock-trading-v1.0",
    "state": "deployed",
    "createdAt": "2026-04-24T07:21:13Z",
    "updatedAt": "2026-04-24T07:21:13Z",
    "deployedAt": "2026-04-24T07:21:13Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	WebBrokerAPI details	WebBrokerApi
404	Not Found	WebBrokerAPI not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Delete a WebBrokerAPI¶

DELETE /webbroker-apis/{id}

Code samples

curl -X DELETE http://localhost:9090/api/management/v0.9/webbroker-apis/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Delete a WebBrokerAPI from the Gateway.

Authentication¶

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebBroker API to delete.

Detailed descriptions

id: Unique public identifier of the WebBroker API to delete.

Example responses

200 Response

{
  "status": "success",
  "message": "WebBrokerAPI deleted successfully",
  "id": "stock-trading-webbroker-api"
}

Responses

Status	Meaning	Description	Schema
200	OK	WebBrokerAPI deleted successfully	Inline
404	Not Found	WebBrokerAPI not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
status	string	false	none	none
message	string	false	none	none
id	string	false	none	none