diff --git a/docs/rest-apis/event-gateway/README.md b/docs/rest-apis/event-gateway/README.md new file mode 100644 index 0000000000..f2edb50f82 --- /dev/null +++ b/docs/rest-apis/event-gateway/README.md @@ -0,0 +1,45 @@ + +

Event Gateway Controller Management API v1.0.0

+ +REST API for managing WebSub and WebBroker API configurations in the +WSO2 API Platform event-gateway-controller. + +Base URLs: +* https://localhost:9090/api/management/v1 +* https://event-gateway-controller:9090/api/management/v1 + +## Table of Contents + +### [Authentication](authentication.md) + +### [WebSub API Management](websub-api-management.md) + +- [Create a new WebSubAPI](websub-api-management.md#create-a-new-websubapi) +- [List all WebSubAPIs](websub-api-management.md#list-all-websubapis) +- [Create a new API key for a WebSub API](websub-api-management.md#create-a-new-api-key-for-a-websub-api) +- [Get the list of API keys for a WebSub API](websub-api-management.md#get-the-list-of-api-keys-for-a-websub-api) +- [Regenerate API key for a WebSub API](websub-api-management.md#regenerate-api-key-for-a-websub-api) +- [Update an API key for a WebSub API](websub-api-management.md#update-an-api-key-for-a-websub-api) +- [Revoke an API key for a WebSub API](websub-api-management.md#revoke-an-api-key-for-a-websub-api) +- [Generate a new HMAC secret for a WebSub API](websub-api-management.md#generate-a-new-hmac-secret-for-a-websub-api) +- [List HMAC secrets for a WebSub API](websub-api-management.md#list-hmac-secrets-for-a-websub-api) +- [Regenerate (rotate) a WebSub API HMAC secret](websub-api-management.md#regenerate-rotate-a-websub-api-hmac-secret) +- [Delete a WebSub API HMAC secret](websub-api-management.md#delete-a-websub-api-hmac-secret) +- [Get WebSubAPI by id](websub-api-management.md#get-websubapi-by-id) +- [Update an existing WebSubAPI](websub-api-management.md#update-an-existing-websubapi) +- [Delete a WebSubAPI](websub-api-management.md#delete-a-websubapi) + +### [WebBroker API Management](webbroker-api-management.md) + +- [Create a new WebBrokerAPI](webbroker-api-management.md#create-a-new-webbrokerapi) +- [List all WebBrokerAPIs](webbroker-api-management.md#list-all-webbrokerapis) +- [Get WebBrokerAPI by id](webbroker-api-management.md#get-webbrokerapi-by-id) +- [Delete a WebBrokerAPI](webbroker-api-management.md#delete-a-webbrokerapi) +- [Create a new API key for a WebBroker API](webbroker-api-management.md#create-a-new-api-key-for-a-webbroker-api) +- [Get the list of API keys for a WebBroker API](webbroker-api-management.md#get-the-list-of-api-keys-for-a-webbroker-api) +- [Regenerate API key for a WebBroker API](webbroker-api-management.md#regenerate-api-key-for-a-webbroker-api) +- [Update an API key for a WebBroker API](webbroker-api-management.md#update-an-api-key-for-a-webbroker-api) +- [Revoke an API key for a WebBroker API](webbroker-api-management.md#revoke-an-api-key-for-a-webbroker-api) + +### [Schemas](schemas.md) + diff --git a/docs/rest-apis/event-gateway/authentication.md b/docs/rest-apis/event-gateway/authentication.md new file mode 100644 index 0000000000..efa7b597b7 --- /dev/null +++ b/docs/rest-apis/event-gateway/authentication.md @@ -0,0 +1,3 @@ +# Authentication + +- HTTP Authentication, scheme: basic diff --git a/docs/rest-apis/event-gateway/schemas.md b/docs/rest-apis/event-gateway/schemas.md new file mode 100644 index 0000000000..2d6d5e9796 --- /dev/null +++ b/docs/rest-apis/event-gateway/schemas.md @@ -0,0 +1,1518 @@ +# Schemas + +

APIKey

+ + + + + + +```json +{ + "name": "my-production-key", + "displayName": "My Production Key", + "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "apiId": "reading-list-api-v1.0", + "status": "active", + "createdAt": "2026-04-01T10:30:00Z", + "createdBy": "admin", + "expiresAt": null, + "source": "local" +} + +``` + +Details of an API key + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|name|string|true|none|URL-safe identifier for the API key (auto-generated from displayName, immutable, used as path parameter)| +|displayName|string|false|none|Human-readable name for the API key (user-provided, mutable)| +|apiKey|string|false|none|Generated API key with apip_ prefix| +|apiId|string|true|none|Unique public identifier of the API that the key is associated with| +|status|string|true|none|Status of the API key| +|createdAt|string(date-time)|true|none|Timestamp when the API key was generated| +|createdBy|string|true|none|Identifier of the user who generated the API key| +|expiresAt|string(date-time)¦null|true|none|Expiration timestamp (null if no expiration)| +|source|string|true|none|Source of the API key (local or external)| +|externalRefId|string|false|none|External reference ID for the API key| + +#### Enumerated Values + +|Property|Value| +|---|---| +|status|active| +|status|revoked| +|status|expired| +|source|local| +|source|external| + +

APIKeyCreationRequest

+ + + + + + +```json +{ + "name": "my-production-key" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|name|string|false|none|Identifier of the API key. If not provided, a default identifier will be generated| +|apiKey|string|false|none|Optional plain-text API key value for external key injection.
If provided, this key will be used instead of generating a new one.
The key will be hashed before storage. The key can be in any format
(minimum 36 characters). Use this for injecting externally generated
API keys.| +|maskedApiKey|string|false|none|Masked version of the API key for display purposes.
Provided by the platform API when injecting pre-hashed keys.| +|expiresIn|object|false|none|Expiration duration for the API key| +|» unit|string|true|none|Time unit for expiration| +|» duration|integer|true|none|Duration value for expiration| +|expiresAt|string(date-time)|false|none|Expiration timestamp. If both expiresIn and expiresAt are provided, expiresAt takes precedence.| +|externalRefId|string|false|none|External reference ID for the API key.
This field is optional and used for tracing purposes only.
The gateway generates its own internal ID for tracking.| +|issuer|string|false|none|Identifies the portal that created this key. If provided, only api keys generated from
the same portal will be accepted. If not provided, there is no portal restriction.| + +#### Enumerated Values + +|Property|Value| +|---|---| +|unit|seconds| +|unit|minutes| +|unit|hours| +|unit|days| +|unit|weeks| +|unit|months| + +

APIKeyCreationResponse

+ + + + + + +```json +{ + "status": "success", + "message": "API key generated successfully", + "remainingApiKeyQuota": 9, + "apiKey": { + "name": "my-production-key", + "displayName": "My Production Key", + "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "apiId": "reading-list-api-v1.0", + "status": "active", + "createdAt": "2026-04-01T10:30:00Z", + "createdBy": "admin", + "expiresAt": null, + "source": "local" + } +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|status|string|true|none|none| +|message|string|true|none|none| +|remainingApiKeyQuota|integer|false|none|Remaining API key quota for the user| +|apiKey|[APIKey](#schemaapikey)|false|none|Details of an API key| + +

APIKeyListResponse

+ + + + + + +```json +{ + "apiKeys": [ + { + "name": "my-production-key", + "displayName": "My Production Key", + "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "apiId": "reading-list-api-v1.0", + "status": "active", + "createdAt": "2026-04-01T10:30:00Z", + "createdBy": "admin", + "expiresAt": null, + "source": "local" + } + ], + "totalCount": 3, + "status": "success" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|apiKeys|[[APIKey](#schemaapikey)]|false|none|[Details of an API key]| +|totalCount|integer|false|none|Total number of API keys| +|status|string|false|none|none| + +

APIKeyRegenerationRequest

+ + + + + + +```json +{} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|expiresIn|object|false|none|Expiration duration for the API key| +|» unit|string|true|none|Time unit for expiration| +|» duration|integer|true|none|Duration value for expiration| +|expiresAt|string(date-time)|false|none|Expiration timestamp| + +#### Enumerated Values + +|Property|Value| +|---|---| +|unit|seconds| +|unit|minutes| +|unit|hours| +|unit|days| +|unit|weeks| +|unit|months| + +

APIKeyRevocationResponse

+ + + + + + +```json +{ + "status": "success", + "message": "API key revoked successfully" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|status|string|true|none|none| +|message|string|true|none|none| + +

APIKeyUpdateRequest

+ + + + + + +```json +{ + "name": "my-production-key" +} + +``` + +### Properties + +*None* + +

ErrorResponse

+ + + + + + +```json +{ + "status": "error", + "message": "Configuration validation failed", + "errors": [ + { + "field": "spec.context", + "message": "Context must start with / and cannot end with /" + } + ] +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|status|string|true|none|none| +|message|string|true|none|High-level error description| +|errors|[[ValidationError](#schemavalidationerror)]|false|none|Detailed validation errors| + +

Metadata

+ + + + + + +```json +{ + "name": "reading-list-api-v1.0", + "labels": { + "environment": "production", + "team": "backend", + "version": "v1" + }, + "annotations": { + "gateway.api-platform.wso2.com/project-id": "019d953f-d386-7a64-aa92-1869a28292e0" + } +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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| + +

Policy

+ + + + + + +```json +{ + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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)| + +

ResourceStatus

+ + + + + + +```json +{ + "id": "reading-list-api-v1.0", + "state": "deployed", + "createdAt": "2026-04-24T07:21:13Z", + "updatedAt": "2026-04-24T07:21:13Z", + "deployedAt": "2026-04-24T07:21:13Z" +} + +``` + +Server-managed lifecycle information for a resource + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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| +|---|---| +|state|deployed| +|state|undeployed| + +

ValidationError

+ + + + + + +```json +{ + "field": "spec.context", + "message": "Context must start with / and cannot end with /" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|field|string|false|none|Field that failed validation| +|message|string|false|none|Human-readable error message| + +

WebBrokerApi

+ + + + + + +```json +{ + "apiVersion": "gateway.api-platform.wso2.com/v1", + "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" + } +} + +``` + +### Properties + +allOf + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|*anonymous*|[WebBrokerApiRequest](#schemawebbrokerapirequest)|false|none|none| + +and + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|*anonymous*|object|false|none|none| +|» status|[ResourceStatus](#schemaresourcestatus)|false|read-only|Server-managed lifecycle fields. Populated on responses.| + +

WebBrokerApiAllChannelPolicies

+ + + + + + +```json +{ + "on_connection_init": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_produce": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_consume": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } +} + +``` + +Protocol mediation policies applied to all channels + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|on_connection_init|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| +|on_produce|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| +|on_consume|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| + +

WebBrokerApiBroker

+ + + + + + +```json +{ + "name": "kafka-driver", + "type": "kafka", + "properties": { + "brokers": [ + "kafka-broker-1:9092", + "kafka-broker-2:9092" + ] + } +} + +``` + +Message broker driver configuration + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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)| + +

WebBrokerApiChannel

+ + + + + + +```json +{ + "produceTo": { + "topic": "stock.prices" + }, + "consumeFrom": { + "topic": "stock.prices" + }, + "on_connection_init": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_produce": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_consume": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } +} + +``` + +WebSocket channel configuration with Kafka topic mapping + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|produceTo|[WebBrokerApiProduceConfig](#schemawebbrokerapiproduceconfig)|false|none|Configuration for producing messages from WebSocket to Kafka| +|consumeFrom|[WebBrokerApiConsumeConfig](#schemawebbrokerapiconsumeconfig)|false|none|Configuration for consuming messages from Kafka to WebSocket| +|on_connection_init|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| +|on_produce|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| +|on_consume|[WebBrokerApiPolicyGroup](#schemawebbrokerapipolicygroup)|false|none|Group of policies| + +

WebBrokerApiConsumeConfig

+ + + + + + +```json +{ + "topic": "stock.prices" +} + +``` + +Configuration for consuming messages from Kafka to WebSocket + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|topic|string|true|none|Kafka topic to consume messages from| + +

WebBrokerApiData

+ + + + + + +```json +{ + "displayName": "Stock Trading WebBroker API", + "version": "v1.0", + "context": "/stock-trading", + "receiver": { + "name": "websocket-receiver", + "type": "websocket", + "properties": {} + }, + "broker": { + "name": "kafka-driver", + "type": "kafka", + "properties": { + "brokers": [ + "kafka-broker-1:9092", + "kafka-broker-2:9092" + ] + } + }, + "allChannels": { + "on_connection_init": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_produce": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_consume": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + }, + "channels": { + "property1": { + "produceTo": { + "topic": "stock.prices" + }, + "consumeFrom": { + "topic": "stock.prices" + }, + "on_connection_init": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_produce": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_consume": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + }, + "property2": { + "produceTo": { + "topic": "stock.prices" + }, + "consumeFrom": { + "topic": "stock.prices" + }, + "on_connection_init": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_produce": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_consume": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + } + }, + "vhosts": { + "main": "api.example.com", + "sandbox": "sandbox-api.example.com" + }, + "deploymentState": "deployed" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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](#schemawebbrokerapireceiver)|true|none|WebSocket receiver configuration| +|broker|[WebBrokerApiBroker](#schemawebbrokerapibroker)|true|none|Message broker driver configuration| +|allChannels|[WebBrokerApiAllChannelPolicies](#schemawebbrokerapiallchannelpolicies)|false|none|Protocol mediation policies applied to all channels| +|channels|object|true|none|Map of WebSocket channels for bidirectional streaming with Kafka (key is channel name)| +|» **additionalProperties**|[WebBrokerApiChannel](#schemawebbrokerapichannel)|false|none|WebSocket channel configuration with Kafka topic mapping| +|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.| + +#### Enumerated Values + +|Property|Value| +|---|---| +|deploymentState|deployed| +|deploymentState|undeployed| + +

WebBrokerApiPolicyGroup

+ + + + + + +```json +{ + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] +} + +``` + +Group of policies + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|policies|[[Policy](#schemapolicy)]|false|none|List of policies to apply| + +

WebBrokerApiProduceConfig

+ + + + + + +```json +{ + "topic": "stock.prices" +} + +``` + +Configuration for producing messages from WebSocket to Kafka + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|topic|string|true|none|Kafka topic to produce messages to| + +

WebBrokerApiReceiver

+ + + + + + +```json +{ + "name": "websocket-receiver", + "type": "websocket", + "properties": {} +} + +``` + +WebSocket receiver configuration + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|name|string|true|none|Receiver name| +|type|string|true|none|Receiver type| +|properties|object|false|none|Additional receiver properties| + +

WebBrokerApiRequest

+ + + + + + +```json +{ + "apiVersion": "gateway.api-platform.wso2.com/v1", + "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": [] + } + } + } + } +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|apiVersion|string|true|none|API specification version| +|kind|string|true|none|API type| +|metadata|[Metadata](#schemametadata)|true|none|none| +|spec|[WebBrokerApiData](#schemawebbrokerapidata)|true|none|none| + +#### Enumerated Values + +|Property|Value| +|---|---| +|apiVersion|gateway.api-platform.wso2.com/v1| +|kind|WebBrokerApi| + +

WebSubAPI

+ + + + + + +```json +{ + "apiVersion": "gateway.api-platform.wso2.com/v1", + "kind": "WebSubApi", + "metadata": { + "name": "github-events-v1.0" + }, + "spec": { + "displayName": "GitHub Events", + "version": "v1.0", + "context": "/github-events/$version", + "channels": [ + { + "name": "issues", + "method": "SUB" + }, + { + "name": "pull_requests", + "method": "SUB" + } + ] + }, + "status": { + "id": "github-events-v1.0", + "state": "deployed", + "createdAt": "2026-04-24T07:21:13Z", + "updatedAt": "2026-04-24T07:21:13Z", + "deployedAt": "2026-04-24T07:21:13Z" + } +} + +``` + +### Properties + +allOf + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|*anonymous*|[WebSubAPIRequest](#schemawebsubapirequest)|false|none|none| + +and + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|*anonymous*|object|false|none|none| +|» status|[ResourceStatus](#schemaresourcestatus)|false|read-only|Server-managed lifecycle fields. Populated on responses.| + +

WebSubAPIRequest

+ + + + + + +```json +{ + "apiVersion": "gateway.api-platform.wso2.com/v1", + "kind": "WebSubApi", + "metadata": { + "name": "github-events-v1.0" + }, + "spec": { + "displayName": "GitHub Events", + "version": "v1.0", + "context": "/github-events/$version", + "channels": [ + { + "name": "issues", + "method": "SUB" + }, + { + "name": "pull_requests", + "method": "SUB" + } + ] + } +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|apiVersion|string|true|none|API specification version| +|kind|string|true|none|API type| +|metadata|[Metadata](#schemametadata)|true|none|none| +|spec|[WebhookAPIData](#schemawebhookapidata)|true|none|none| + +#### Enumerated Values + +|Property|Value| +|---|---| +|apiVersion|gateway.api-platform.wso2.com/v1| +|kind|WebSubApi| + +

WebSubAllChannelPolicies

+ + + + + + +```json +{ + "on_subscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_unsubscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_received": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_delivery": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } +} + +``` + +Policies applied to all channels, organized by event type. + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|on_subscription|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_unsubscription|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_message_received|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_message_delivery|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| + +

WebSubChannel

+ + + + + + +```json +{ + "on_subscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_unsubscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_received": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_delivery": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } +} + +``` + +A single channel definition with optional per-channel policy overrides. + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|on_subscription|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_unsubscription|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_message_received|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| +|on_message_delivery|[WebSubEventPolicies](#schemawebsubeventpolicies)|false|none|Policies for a single event type.| + +

WebSubEventPolicies

+ + + + + + +```json +{ + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] +} + +``` + +Policies for a single event type. + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|policies|[[Policy](#schemapolicy)]|false|none|List of policies applied for this event type.| + +

WebhookAPIData

+ + + + + + +```json +{ + "displayName": "reading-list-api", + "version": "v1.0", + "context": "/weather", + "vhosts": { + "main": "api.example.com", + "sandbox": "sandbox-api.example.com" + }, + "allChannels": { + "on_subscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_unsubscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_received": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_delivery": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + }, + "channels": { + "property1": { + "on_subscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_unsubscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_received": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_delivery": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + }, + "property2": { + "on_subscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_unsubscription": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_received": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + }, + "on_message_delivery": { + "policies": [ + { + "name": "cors", + "version": "v1", + "executionCondition": "request.metadata[authenticated] != true", + "params": {} + } + ] + } + } + }, + "deploymentState": "deployed" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|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)| +|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| +|allChannels|[WebSubAllChannelPolicies](#schemawebsuballchannelpolicies)|false|none|Policies applied to all channels, organized by event type.| +|channels|object|false|none|Per-channel configuration keyed by channel name. Each key is a channel name and defines policies applied only to that channel.| +|» **additionalProperties**|[WebSubChannel](#schemawebsubchannel)|false|none|A single channel definition with optional per-channel policy overrides.| +|deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration, API keys, and policies are preserved for potential redeployment.| + +#### Enumerated Values + +|Property|Value| +|---|---| +|deploymentState|deployed| +|deploymentState|undeployed| + +

WebhookSecretCreationRequest

+ + + + + + +```json +{ + "displayName": "GitHub Webhook" +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|displayName|string|true|none|Human-readable label for this secret (used to derive the immutable name slug).| + +

WebhookSecretCreationResponse

+ + + + + + +```json +{ + "status": "success", + "message": "Webhook secret generated successfully", + "secret": "whsec_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", + "webhookSecret": { + "name": "github-webhook", + "displayName": "GitHub Webhook", + "status": "active", + "createdAt": "2026-06-01T10:00:00Z", + "updatedAt": "2026-06-01T10:00:00Z" + } +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|status|string|true|none|none| +|message|string|true|none|none| +|secret|string|true|none|The generated plaintext secret value (whsec_ prefix + 64 hex chars).
Returned exactly once — store it immediately as it will not be retrievable again.| +|webhookSecret|[WebhookSecretInfo](#schemawebhooksecretinfo)|false|none|Metadata for an HMAC secret. The plaintext value is never included.| + +

WebhookSecretInfo

+ + + + + + +```json +{ + "name": "github-webhook", + "displayName": "GitHub Webhook", + "status": "active", + "createdAt": "2026-06-01T10:00:00Z", + "updatedAt": "2026-06-01T10:00:00Z" +} + +``` + +Metadata for an HMAC secret. The plaintext value is never included. + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|name|string|false|none|URL-safe slug (immutable, used as path parameter for regenerate/delete).| +|displayName|string|false|none|Human-readable label.| +|status|string|false|none|none| +|createdAt|string(date-time)|false|none|none| +|updatedAt|string(date-time)|false|none|none| + +#### Enumerated Values + +|Property|Value| +|---|---| +|status|active| +|status|revoked| + +

WebhookSecretListResponse

+ + + + + + +```json +{ + "status": "success", + "totalCount": 2, + "secrets": [ + { + "name": "github-webhook", + "displayName": "GitHub Webhook", + "status": "active", + "createdAt": "2026-06-01T10:00:00Z", + "updatedAt": "2026-06-01T10:00:00Z" + } + ] +} + +``` + +### Properties + +|Name|Type|Required|Restrictions|Description| +|---|---|---|---|---| +|status|string|false|none|none| +|totalCount|integer|false|none|Total number of active secrets for this API| +|secrets|[[WebhookSecretInfo](#schemawebhooksecretinfo)]|false|none|[Metadata for an HMAC secret. The plaintext value is never included.]| diff --git a/docs/rest-apis/gateway/webbroker-api-management.md b/docs/rest-apis/event-gateway/webbroker-api-management.md similarity index 96% rename from docs/rest-apis/gateway/webbroker-api-management.md rename to docs/rest-apis/event-gateway/webbroker-api-management.md index ba886904f1..06a73e80d7 100644 --- a/docs/rest-apis/gateway/webbroker-api-management.md +++ b/docs/rest-apis/event-gateway/webbroker-api-management.md @@ -1,4 +1,4 @@ -

WebBroker API Management

+

WebBroker API Management

## Create a new WebBrokerAPI @@ -10,7 +10,7 @@ ```shell -curl -X POST http://localhost:9090/api/management/v1/webbroker-apis \ +curl -X POST https://localhost:9090/api/management/v1/webbroker-apis \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -97,7 +97,7 @@ Required roles: `admin`, `developer` |body|body|[WebBrokerApiRequest](schemas.md#schemawebbrokerapirequest)|true|none| > Example responses - +> > 201 Response ```json @@ -185,7 +185,7 @@ Required roles: `admin`, `developer` ```shell -curl -X GET http://localhost:9090/api/management/v1/webbroker-apis \ +curl -X GET https://localhost:9090/api/management/v1/webbroker-apis \ -u {username}:{password} \ -H 'Accept: application/json' @@ -218,7 +218,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -391,7 +391,7 @@ Status Code **200** ```shell -curl -X GET http://localhost:9090/api/management/v1/webbroker-apis/{id} \ +curl -X GET https://localhost:9090/api/management/v1/webbroker-apis/{id} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -419,7 +419,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier for the WebBroker API. > Example responses - +> > 200 Response ```json @@ -506,7 +506,7 @@ Required roles: `admin`, `developer` ```shell -curl -X DELETE http://localhost:9090/api/management/v1/webbroker-apis/{id} \ +curl -X DELETE https://localhost:9090/api/management/v1/webbroker-apis/{id} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -534,7 +534,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the WebBroker API to delete. > Example responses - +> > 200 Response ```json @@ -573,7 +573,7 @@ Status Code **200** ```shell -curl -X POST http://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys \ +curl -X POST https://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -608,7 +608,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyCreationRequest](schemas.md#schemaapikeycreationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -650,7 +650,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X GET http://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys \ +curl -X GET https://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys \ -u {username}:{password} \ -H 'Accept: application/json' @@ -674,7 +674,7 @@ Required roles: `admin`, `consumer` |id|path|string|true|Unique public identifier of the WebBroker API to retrieve the keys for| > Example responses - +> > 200 Response ```json @@ -715,7 +715,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X POST http://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName}/regenerate \ +curl -X POST https://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName}/regenerate \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -749,7 +749,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyRegenerationRequest](schemas.md#schemaapikeyregenerationrequest)|true|none| > Example responses - +> > 200 Response ```json @@ -790,7 +790,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X PUT http://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName} \ +curl -X PUT https://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName} \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -826,7 +826,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyUpdateRequest](schemas.md#schemaapikeyupdaterequest)|true|none| > Example responses - +> > 200 Response ```json @@ -868,7 +868,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X DELETE http://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName} \ +curl -X DELETE https://localhost:9090/api/management/v1/webbroker-apis/{id}/api-keys/{apiKeyName} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -893,7 +893,7 @@ Required roles: `admin`, `consumer` |apiKeyName|path|string|true|Name of the API key to revoke| > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/websub-api-management.md b/docs/rest-apis/event-gateway/websub-api-management.md similarity index 96% rename from docs/rest-apis/gateway/websub-api-management.md rename to docs/rest-apis/event-gateway/websub-api-management.md index 834b6cc454..06f3cc8396 100644 --- a/docs/rest-apis/gateway/websub-api-management.md +++ b/docs/rest-apis/event-gateway/websub-api-management.md @@ -1,4 +1,4 @@ -

WebSub API Management

+

WebSub API Management

## Create a new WebSubAPI @@ -10,7 +10,7 @@ ```shell -curl -X POST http://localhost:9090/api/management/v1/websub-apis \ +curl -X POST https://localhost:9090/api/management/v1/websub-apis \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -63,7 +63,7 @@ Required roles: `admin`, `developer` |body|body|[WebSubAPIRequest](schemas.md#schemawebsubapirequest)|true|none| > Example responses - +> > 201 Response ```json @@ -117,7 +117,7 @@ Required roles: `admin`, `developer` ```shell -curl -X GET http://localhost:9090/api/management/v1/websub-apis \ +curl -X GET https://localhost:9090/api/management/v1/websub-apis \ -u {username}:{password} \ -H 'Accept: application/json' @@ -151,7 +151,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -280,7 +280,7 @@ Status Code **200** ```shell -curl -X POST http://localhost:9090/api/management/v1/websub-apis/{id}/api-keys \ +curl -X POST https://localhost:9090/api/management/v1/websub-apis/{id}/api-keys \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -315,7 +315,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyCreationRequest](schemas.md#schemaapikeycreationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -357,7 +357,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X GET http://localhost:9090/api/management/v1/websub-apis/{id}/api-keys \ +curl -X GET https://localhost:9090/api/management/v1/websub-apis/{id}/api-keys \ -u {username}:{password} \ -H 'Accept: application/json' @@ -381,7 +381,7 @@ Required roles: `admin`, `consumer` |id|path|string|true|Unique public identifier of the WebSub API to retrieve the keys for| > Example responses - +> > 200 Response ```json @@ -422,7 +422,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X POST http://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName}/regenerate \ +curl -X POST https://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName}/regenerate \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -456,7 +456,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyRegenerationRequest](schemas.md#schemaapikeyregenerationrequest)|true|none| > Example responses - +> > 200 Response ```json @@ -497,7 +497,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X PUT http://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName} \ +curl -X PUT https://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName} \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -533,7 +533,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyUpdateRequest](schemas.md#schemaapikeyupdaterequest)|true|none| > Example responses - +> > 200 Response ```json @@ -575,7 +575,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X DELETE http://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName} \ +curl -X DELETE https://localhost:9090/api/management/v1/websub-apis/{id}/api-keys/{apiKeyName} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -600,7 +600,7 @@ Required roles: `admin`, `consumer` |apiKeyName|path|string|true|Name of the API key to revoke| > Example responses - +> > 200 Response ```json @@ -629,7 +629,7 @@ Required roles: `admin`, `consumer` ```shell -curl -X POST http://localhost:9090/api/management/v1/websub-apis/{id}/secrets \ +curl -X POST https://localhost:9090/api/management/v1/websub-apis/{id}/secrets \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -667,7 +667,7 @@ Required roles: `admin`, `developer` |body|body|[WebhookSecretCreationRequest](schemas.md#schemawebhooksecretcreationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -705,7 +705,7 @@ Required roles: `admin`, `developer` ```shell -curl -X GET http://localhost:9090/api/management/v1/websub-apis/{id}/secrets \ +curl -X GET https://localhost:9090/api/management/v1/websub-apis/{id}/secrets \ -u {username}:{password} \ -H 'Accept: application/json' @@ -729,7 +729,7 @@ Required roles: `admin`, `developer` |id|path|string|true|Unique public identifier of the WebSub API| > Example responses - +> > 200 Response ```json @@ -766,7 +766,7 @@ Required roles: `admin`, `developer` ```shell -curl -X POST http://localhost:9090/api/management/v1/websub-apis/{id}/secrets/{secretName}/regenerate \ +curl -X POST https://localhost:9090/api/management/v1/websub-apis/{id}/secrets/{secretName}/regenerate \ -u {username}:{password} \ -H 'Accept: application/json' @@ -793,7 +793,7 @@ Required roles: `admin`, `developer` |secretName|path|string|true|Name of the secret to regenerate| > Example responses - +> > 200 Response ```json @@ -829,7 +829,7 @@ Required roles: `admin`, `developer` ```shell -curl -X DELETE http://localhost:9090/api/management/v1/websub-apis/{id}/secrets/{secretName} \ +curl -X DELETE https://localhost:9090/api/management/v1/websub-apis/{id}/secrets/{secretName} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -854,7 +854,7 @@ Required roles: `admin`, `developer` |secretName|path|string|true|Name of the secret to delete| > Example responses - +> > 404 Response ```json @@ -888,7 +888,7 @@ Required roles: `admin`, `developer` ```shell -curl -X GET http://localhost:9090/api/management/v1/websub-apis/{id} \ +curl -X GET https://localhost:9090/api/management/v1/websub-apis/{id} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -916,7 +916,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier for the WebSub API. > Example responses - +> > 200 Response ```json @@ -969,7 +969,7 @@ Required roles: `admin`, `developer` ```shell -curl -X PUT http://localhost:9090/api/management/v1/websub-apis/{id} \ +curl -X PUT https://localhost:9090/api/management/v1/websub-apis/{id} \ -u {username}:{password} \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ @@ -1027,7 +1027,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the WebSub API to update. > Example responses - +> > 200 Response ```json @@ -1081,7 +1081,7 @@ Required roles: `admin`, `developer` ```shell -curl -X DELETE http://localhost:9090/api/management/v1/websub-apis/{id} \ +curl -X DELETE https://localhost:9090/api/management/v1/websub-apis/{id} \ -u {username}:{password} \ -H 'Accept: application/json' @@ -1109,7 +1109,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the WebSub API to delete. > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/certificate-management.md b/docs/rest-apis/gateway/certificate-management.md index ebc46de136..71cc133580 100644 --- a/docs/rest-apis/gateway/certificate-management.md +++ b/docs/rest-apis/gateway/certificate-management.md @@ -31,7 +31,7 @@ Required roles: `admin`, `developer` > Example responses - +> > 200 Response ```json @@ -106,7 +106,7 @@ Required roles: `admin` |body|body|[CertificateUploadRequest](schemas.md#schemacertificateuploadrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -164,7 +164,7 @@ Required roles: `admin` |id|path|string|true|ID of the certificate to delete| > Example responses - +> > 200 Response ```json @@ -221,7 +221,7 @@ Required roles: `admin` > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/llm-provider-management.md b/docs/rest-apis/gateway/llm-provider-management.md index 5d6ffbc4ef..477251dff0 100644 --- a/docs/rest-apis/gateway/llm-provider-management.md +++ b/docs/rest-apis/gateway/llm-provider-management.md @@ -87,7 +87,7 @@ Required roles: `admin` |body|body|[LLMProviderConfigurationRequest](schemas.md#schemallmproviderconfigurationrequest)|true|LLM provider in YAML or JSON format| > Example responses - +> > 201 Response ```json @@ -106,8 +106,7 @@ Required roles: `admin` "url": "https://api.openai.com/v1", "auth": { "type": "api-key", - "header": "Authorization", - "value": "Bearer sk-your-api-key" + "header": "Authorization" } }, "accessControl": { @@ -198,7 +197,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -221,8 +220,7 @@ Required roles: `admin`, `developer` "url": "https://api.openai.com/v1", "auth": { "type": "api-key", - "header": "Authorization", - "value": "Bearer sk-your-api-key" + "header": "Authorization" } }, "accessControl": { @@ -336,7 +334,7 @@ Status Code **200** |»»»»»» auth|object|false|none|none| |»»»»»»» type|string|true|none|none| |»»»»»»» header|string|false|none|none| -|»»»»»»» value|string|false|none|none| +|»»»»»»» value|string|false|write-only|Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. Supply either a literal value or a secret reference (e.g. a `secret` template expression); either way the field is omitted from management API response bodies. An update that omits it inherits the stored value; set `type: none` to remove auth.| *continued* @@ -436,7 +434,7 @@ Required roles: `admin`, `developer` |id|path|string|true|Unique identifier of the LLM provider| > Example responses - +> > 200 Response ```json @@ -455,8 +453,7 @@ Required roles: `admin`, `developer` "url": "https://api.openai.com/v1", "auth": { "type": "api-key", - "header": "Authorization", - "value": "Bearer sk-your-api-key" + "header": "Authorization" } }, "accessControl": { @@ -587,7 +584,7 @@ Required roles: `admin` |body|body|[LLMProviderConfigurationRequest](schemas.md#schemallmproviderconfigurationrequest)|true|Updated LLM provider| > Example responses - +> > 200 Response ```json @@ -606,8 +603,7 @@ Required roles: `admin` "url": "https://api.openai.com/v1", "auth": { "type": "api-key", - "header": "Authorization", - "value": "Bearer sk-your-api-key" + "header": "Authorization" } }, "accessControl": { @@ -687,7 +683,7 @@ Required roles: `admin` |id|path|string|true|Unique identifier of the LLM provider| > Example responses - +> > 200 Response ```json @@ -761,7 +757,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyCreationRequest](schemas.md#schemaapikeycreationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -827,7 +823,7 @@ Required roles: `admin`, `consumer` |id|path|string|true|Unique handle of the LLM provider to retrieve keys for| > Example responses - +> > 200 Response ```json @@ -902,7 +898,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyRegenerationRequest](schemas.md#schemaapikeyregenerationrequest)|true|none| > Example responses - +> > 200 Response ```json @@ -979,7 +975,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyUpdateRequest](schemas.md#schemaapikeyupdaterequest)|true|none| > Example responses - +> > 200 Response ```json @@ -1046,7 +1042,7 @@ Required roles: `admin`, `consumer` |apiKeyName|path|string|true|Name of the API key to revoke| > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/llm-provider-template-management.md b/docs/rest-apis/gateway/llm-provider-template-management.md index fb1f02c80f..11c6b7c0cf 100644 --- a/docs/rest-apis/gateway/llm-provider-template-management.md +++ b/docs/rest-apis/gateway/llm-provider-template-management.md @@ -77,7 +77,7 @@ Required roles: `admin` |body|body|[LLMProviderTemplateRequest](schemas.md#schemallmprovidertemplaterequest)|true|none| > Example responses - +> > 201 Response ```json @@ -165,7 +165,7 @@ Required roles: `admin` |displayName|query|string|false|Filter by template display name| > Example responses - +> > 200 Response ```json @@ -328,7 +328,7 @@ Required roles: `admin` |id|path|string|true|Unique public identifier for the LLM provider template| > Example responses - +> > 200 Response ```json @@ -457,7 +457,7 @@ Required roles: `admin` |body|body|[LLMProviderTemplateRequest](schemas.md#schemallmprovidertemplaterequest)|true|none| > Example responses - +> > 200 Response ```json @@ -545,7 +545,7 @@ Required roles: `admin` |id|path|string|true|Unique public identifier of the template to delete| > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/llm-proxy-management.md b/docs/rest-apis/gateway/llm-proxy-management.md index 8e1cd39bfb..09b5c04428 100644 --- a/docs/rest-apis/gateway/llm-proxy-management.md +++ b/docs/rest-apis/gateway/llm-proxy-management.md @@ -59,7 +59,7 @@ Required roles: `admin`, `developer` |body|body|[LLMProxyConfigurationRequest](schemas.md#schemallmproxyconfigurationrequest)|true|LLM proxy in YAML or JSON format| > Example responses - +> > 201 Response ```json @@ -142,7 +142,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -217,7 +217,7 @@ Status Code **200** |»»»»» auth|[LLMUpstreamAuth](schemas.md#schemallmupstreamauth)|false|none|none| |»»»»»» type|string|true|none|none| |»»»»»» header|string|false|none|none| -|»»»»»» value|string|false|none|none| +|»»»»»» value|string|false|write-only|Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. An update that omits it inherits the stored value; set `type: none` to remove auth.| |»»»» globalPolicies|[[Policy](schemas.md#schemapolicy)]|false|none|Global (api-level) policies applied across ALL operations as one shared scope, evaluated before operation-level policies.| |»»»»» 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.| @@ -311,7 +311,7 @@ Required roles: `admin`, `developer` |id|path|string|true|Unique identifier of the LLM proxy| > Example responses - +> > 200 Response ```json @@ -406,7 +406,7 @@ Required roles: `admin`, `developer` |body|body|[LLMProxyConfigurationRequest](schemas.md#schemallmproxyconfigurationrequest)|true|Updated LLM proxy| > Example responses - +> > 200 Response ```json @@ -478,7 +478,7 @@ Required roles: `admin`, `developer` |id|path|string|true|Unique identifier of the LLM proxy| > Example responses - +> > 200 Response ```json @@ -552,7 +552,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyCreationRequest](schemas.md#schemaapikeycreationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -618,7 +618,7 @@ Required roles: `admin`, `consumer` |id|path|string|true|Unique handle of the LLM proxy to retrieve keys for| > Example responses - +> > 200 Response ```json @@ -693,7 +693,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyRegenerationRequest](schemas.md#schemaapikeyregenerationrequest)|true|none| > Example responses - +> > 200 Response ```json @@ -770,7 +770,7 @@ Required roles: `admin`, `consumer` |body|body|[APIKeyUpdateRequest](schemas.md#schemaapikeyupdaterequest)|true|none| > Example responses - +> > 200 Response ```json @@ -837,7 +837,7 @@ Required roles: `admin`, `consumer` |apiKeyName|path|string|true|Name of the API key to revoke| > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/mcp-proxy-management.md b/docs/rest-apis/gateway/mcp-proxy-management.md index b2fdbc2943..8a1cbda355 100644 --- a/docs/rest-apis/gateway/mcp-proxy-management.md +++ b/docs/rest-apis/gateway/mcp-proxy-management.md @@ -62,7 +62,7 @@ Required roles: `admin`, `developer` |body|body|[MCPProxyConfigurationRequest](schemas.md#schemamcpproxyconfigurationrequest)|true|none| > Example responses - +> > 201 Response ```json @@ -147,7 +147,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -260,7 +260,7 @@ Status Code **200** |»»»»»» auth|object|false|none|none| |»»»»»»» type|string|true|none|none| |»»»»»»» header|string|false|none|none| -|»»»»»»» value|string|false|none|none| +|»»»»»»» value|string|false|write-only|Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. Supply either a literal value or a secret reference (e.g. a `secret` template expression); either way the field is omitted from management API response bodies. An update that omits it inherits the stored value; set `type: none` to remove auth.| *continued* @@ -364,7 +364,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the MCP Proxy. > Example responses - +> > 200 Response ```json @@ -469,7 +469,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the MCP Proxy to update. > Example responses - +> > 200 Response ```json @@ -548,7 +548,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the MCP Proxy to delete. > Example responses - +> > 200 Response ```json diff --git a/docs/rest-apis/gateway/rest-api-management.md b/docs/rest-apis/gateway/rest-api-management.md index e0415c8ee3..caa0e7d8ea 100644 --- a/docs/rest-apis/gateway/rest-api-management.md +++ b/docs/rest-apis/gateway/rest-api-management.md @@ -106,7 +106,7 @@ Required roles: `admin`, `developer` |body|body|[RestAPIRequest](schemas.md#schemarestapirequest)|true|none| > Example responses - +> > 201 Response ```json @@ -235,7 +235,7 @@ Required roles: `admin`, `developer` |status|undeployed| > Example responses - +> > 200 Response ```json @@ -491,7 +491,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier for the API. > Example responses - +> > 200 Response ```json @@ -684,7 +684,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the API to update. > Example responses - +> > 200 Response ```json @@ -807,7 +807,7 @@ Required roles: `admin`, `developer` **id**: Unique public identifier of the API to delete. > Example responses - +> > 200 Response ```json @@ -885,7 +885,7 @@ Required roles: `admin`, `consumer` **id**: Unique public identifier of the API to generate the key for > Example responses - +> > 201 Response ```json @@ -954,7 +954,7 @@ Required roles: `admin`, `consumer` **id**: Unique public identifier of the API to retrieve the keys for > Example responses - +> > 200 Response ```json @@ -1035,7 +1035,7 @@ Required roles: `admin`, `consumer` **apiKeyName**: Name of the API key to regenerate > Example responses - +> > 200 Response ```json @@ -1118,7 +1118,7 @@ Required roles: `admin`, `consumer` **apiKeyName**: Name of the API key to update > Example responses - +> > 200 Response ```json @@ -1190,7 +1190,7 @@ Required roles: `admin`, `consumer` **apiKeyName**: Name of the API key to revoke > Example responses - +> > 200 Response ```json @@ -1248,7 +1248,7 @@ Create a subscription plan that defines rate limits and access tiers for API sub @@ -1259,7 +1259,7 @@ Required roles: `admin`, `developer` |body|body|[SubscriptionPlanCreateRequest](schemas.md#schemasubscriptionplancreaterequest)|true|none| > Example responses - +> > 201 Response ```json @@ -1310,12 +1310,12 @@ List all subscription plans available in the Gateway. > Example responses - +> > 200 Response ```json @@ -1369,7 +1369,7 @@ Get the details of a subscription plan by its ID. @@ -1380,7 +1380,7 @@ Required roles: `admin`, `developer` |planId|path|string|true|none| > Example responses - +> > 200 Response ```json @@ -1446,7 +1446,7 @@ Update an existing subscription plan in the Gateway. @@ -1458,7 +1458,7 @@ Required roles: `admin`, `developer` |body|body|[SubscriptionPlanUpdateRequest](schemas.md#schemasubscriptionplanupdaterequest)|false|none| > Example responses - +> > 200 Response ```json @@ -1508,7 +1508,7 @@ Delete a subscription plan from the Gateway. @@ -1519,7 +1519,7 @@ Required roles: `admin`, `developer` |planId|path|string|true|none| > Example responses - +> > 404 Response ```json @@ -1582,7 +1582,7 @@ Subscribe an application to a RestAPI in the Gateway. @@ -1593,7 +1593,7 @@ Required roles: `admin`, `developer` |body|body|[SubscriptionCreateRequest](schemas.md#schemasubscriptioncreaterequest)|true|none| > Example responses - +> > 201 Response ```json @@ -1644,7 +1644,7 @@ List subscriptions in the Gateway, optionally filtered by API, application, or s @@ -1665,7 +1665,7 @@ Required roles: `admin`, `developer` |status|REVOKED| > Example responses - +> > 200 Response ```json @@ -1719,7 +1719,7 @@ Get the details of a subscription by its ID. @@ -1730,7 +1730,7 @@ Required roles: `admin`, `developer` |subscriptionId|path|string|true|none| > Example responses - +> > 200 Response ```json @@ -1790,7 +1790,7 @@ Update an existing subscription in the Gateway. @@ -1802,7 +1802,7 @@ Required roles: `admin`, `developer` |body|body|[SubscriptionUpdateRequest](schemas.md#schemasubscriptionupdaterequest)|false|none| > Example responses - +> > 200 Response ```json @@ -1852,7 +1852,7 @@ Delete a subscription from the Gateway. @@ -1863,7 +1863,7 @@ Required roles: `admin`, `developer` |subscriptionId|path|string|true|none| > Example responses - +> > 404 Response ```json diff --git a/docs/rest-apis/gateway/schemas.md b/docs/rest-apis/gateway/schemas.md index 343d6cbe30..de64a9166a 100644 --- a/docs/rest-apis/gateway/schemas.md +++ b/docs/rest-apis/gateway/schemas.md @@ -2081,8 +2081,7 @@ and "url": "https://api.openai.com/v1", "auth": { "type": "api-key", - "header": "Authorization", - "value": "Bearer sk-your-api-key" + "header": "Authorization" } }, "accessControl": { @@ -2300,7 +2299,7 @@ continued |auth|object|false|none|none| |» type|string|true|none|none| |» header|string|false|none|none| -|» value|string|false|none|none| +|» value|string|false|write-only|Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. Supply either a literal value or a secret reference (e.g. a `secret` template expression); either way the field is omitted from management API response bodies. An update that omits it inherits the stored value; set `type: none` to remove auth.| #### Enumerated Values @@ -2332,7 +2331,7 @@ continued |---|---|---|---|---| |type|string|true|none|none| |header|string|false|none|none| -|value|string|false|none|none| +|value|string|false|write-only|Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. An update that omits it inherits the stored value; set `type: none` to remove auth.| #### Enumerated Values diff --git a/docs/rest-apis/gateway/secrets-management.md b/docs/rest-apis/gateway/secrets-management.md index ecc4d5517b..d5b7aebd74 100644 --- a/docs/rest-apis/gateway/secrets-management.md +++ b/docs/rest-apis/gateway/secrets-management.md @@ -31,7 +31,7 @@ Required roles: `admin` > Example responses - +> > 200 Response ```json @@ -120,7 +120,7 @@ Required roles: `admin` |body|body|[SecretConfigurationRequest](schemas.md#schemasecretconfigurationrequest)|true|none| > Example responses - +> > Secret created successfully ```json @@ -203,7 +203,7 @@ Required roles: `admin` |id|path|string|true|Unique secret identifier| > Example responses - +> > Secret retrieved and decrypted successfully ```json @@ -306,7 +306,7 @@ Required roles: `admin` |id|path|string|true|Unique secret identifier| > Example responses - +> > Secret updated successfully ```json @@ -389,7 +389,7 @@ Required roles: `admin` |id|path|string|true|Unique secret identifier| > Example responses - +> > 401 Response ```json diff --git a/docs/rest-apis/platform-api/README.md b/docs/rest-apis/platform-api/README.md index 7c63c4011b..8d90e4b0b6 100644 --- a/docs/rest-apis/platform-api/README.md +++ b/docs/rest-apis/platform-api/README.md @@ -165,7 +165,7 @@ License: Apache 2.0 @@ -19,6 +19,8 @@ curl -X GET https://localhost:9243/api/v0.9/me/api-keys \ ``` Returns API keys created by the caller within the organization. +Callers holding the `ap:api_key:all:manage` scope instead receive every user's API keys +in the organization; the `createdBy` field identifies each key's creator. Optionally filter by one or more artifact types using a comma-separated `type` query parameter. The plain key value is never returned. @@ -27,11 +29,11 @@ The plain key value is never returned. -

Parameters

+

Parameters

|Name|In|Type|Required|Description| |---|---|---|---|---| @@ -104,7 +106,7 @@ If omitted, all types are returned. } ``` -

Responses

+

Responses

|Status|Meaning|Description|Schema| |---|---|---|---| diff --git a/docs/rest-apis/platform-api/applications.md b/docs/rest-apis/platform-api/applications.md index 2b3a8b6987..0dca16989a 100644 --- a/docs/rest-apis/platform-api/applications.md +++ b/docs/rest-apis/platform-api/applications.md @@ -664,7 +664,7 @@ Lists all API keys mapped to the specified application. @@ -817,7 +817,7 @@ Adds API key mappings to the specified application. @@ -952,7 +952,7 @@ Removes a mapped API key from the specified application. @@ -1442,7 +1442,7 @@ Lists API keys mapped to the specified application for the given associated targ diff --git a/docs/rest-apis/platform-api/llm-providers.md b/docs/rest-apis/platform-api/llm-providers.md index 53cd79a143..a5e3421012 100644 --- a/docs/rest-apis/platform-api/llm-providers.md +++ b/docs/rest-apis/platform-api/llm-providers.md @@ -1716,7 +1716,7 @@ authenticate requests to the LLM provider when API key validation is enabled. @@ -1838,7 +1838,7 @@ Returns all API keys associated with the specified LLM provider. The plain key v @@ -1942,7 +1942,7 @@ Deletes the key from the database and broadcasts a revoke event to the allowed g diff --git a/docs/rest-apis/platform-api/llm-proxies.md b/docs/rest-apis/platform-api/llm-proxies.md index 870bfd7d98..1d05b19ad1 100644 --- a/docs/rest-apis/platform-api/llm-proxies.md +++ b/docs/rest-apis/platform-api/llm-proxies.md @@ -1023,7 +1023,7 @@ authenticate requests to the LLM proxy when API key validation is enabled. @@ -1145,7 +1145,7 @@ Returns all API keys associated with the specified LLM proxy. The plain key valu @@ -1249,7 +1249,7 @@ Deletes the key from the database and broadcasts a revoke event to the allowed g diff --git a/docs/rest-apis/platform-api/rest-apis.md b/docs/rest-apis/platform-api/rest-apis.md index 9a69c34382..5e2fdd9dc1 100644 --- a/docs/rest-apis/platform-api/rest-apis.md +++ b/docs/rest-apis/platform-api/rest-apis.md @@ -1512,7 +1512,7 @@ allows external platforms to inject API keys to hybrid gateways. @@ -1669,7 +1669,7 @@ This endpoint allows external platforms to rotate API keys on hybrid gateways. @@ -1802,7 +1802,7 @@ to revoke API keys on hybrid gateways. diff --git a/docs/rest-apis/platform-api/schemas.md b/docs/rest-apis/platform-api/schemas.md index e6b8c72b32..605a8540f3 100644 --- a/docs/rest-apis/platform-api/schemas.md +++ b/docs/rest-apis/platform-api/schemas.md @@ -35,7 +35,7 @@ |createdBy|string|true|read-only|User identifier of the user who created this resource| |updatedAt|string(date-time)|true|none|Timestamp when the key was last updated| |expiresAt|string(date-time)|false|none|Optional expiration timestamp| -|issuer|string|false|none|Optional identifier of the developer portal that provisioned this key| +|issuer|string|false|none|Optional identifier of the API Portal that provisioned this key| |allowedTargets|string|true|none|Comma-separated list of allowed gateways; 'ALL' means unrestricted| #### Enumerated Values @@ -2117,7 +2117,7 @@ Time unit for API key expiration duration |externalRefId|string¦null|false|none|Optional reference ID for tracing purposes (from external platforms)| |expiresAt|string(date-time)¦null|false|none|Optional expiration time in ISO 8601 format| |expiresIn|[ExpirationDuration](#schemaexpirationduration)|false|none|Optional expiration duration| -|issuer|string¦null|false|none|Identifier of the developer portal that provisioned this API key. Null if not provided.| +|issuer|string¦null|false|none|Identifier of the API Portal that provisioned this API key. Null if not provided.|

CreateAPIKeyResponse

@@ -4771,7 +4771,7 @@ Request/response translator applied when this provider is the selected upstream. |id|string|false|none|Unique identifier for the API key within the LLM provider. If not provided, generated from displayName.| |displayName|string|true|none|Human-readable name for the API key| |expiresAt|string(date-time)|false|none|Optional expiration time in ISO 8601 format| -|issuer|string¦null|false|none|Identifier of the developer portal that provisioned this API key. Null if not provided.| +|issuer|string¦null|false|none|Identifier of the API Portal that provisioned this API key. Null if not provided.| |allowedTargets|string¦null|false|none|Comma-separated list of gateways this key is valid for.
Use 'ALL' to allow all targets (default).|

CreateLLMProviderAPIKeyResponse

@@ -4825,7 +4825,7 @@ Request/response translator applied when this provider is the selected upstream. |id|string|false|none|Unique identifier for the API key within the LLM proxy. If not provided, generated from displayName.| |displayName|string|true|none|Human-readable name for the API key| |expiresAt|string(date-time)|false|none|Optional expiration time in ISO 8601 format| -|issuer|string¦null|false|none|Identifier of the developer portal that provisioned this API key. Null if not provided.| +|issuer|string¦null|false|none|Identifier of the API Portal that provisioned this API key. Null if not provided.| |allowedTargets|string¦null|false|none|Comma-separated list of gateways this key is valid for.
Use 'ALL' to allow all targets (default).|

CreateLLMProxyAPIKeyResponse

@@ -5072,26 +5072,24 @@ Request/response translator applied when this provider is the selected upstream. ``` -Target MCP server to introspect. Provide exactly one of `url` (a direct backend URL, -optionally with `auth`) or `proxyId` (refetch using a stored proxy configuration) — never -both. `auth` must not be sent together with `proxyId`; the stored auth is always used in -the refetch flow. +Target MCP server to introspect, and the credentials to introspect it with. At least +one of `url`/`proxyId` must be provided ### Properties |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -|url|string(uri)|false|none|Endpoint URL of the MCP server to fetch information from. Mutually exclusive
with `proxyId`; exactly one of the two must be provided.| -|proxyId|string|false|none|MCP proxy handle (identifier) for refresh operations. When provided, the server
fetches URL and auth from the stored proxy configuration. Mutually exclusive
with `url`; exactly one of the two must be provided.| -|auth|[UpstreamAuth](#schemaupstreamauth)|false|none|Authentication configuration for the fetch request. Allowed only alongside
`url` (initial creation flow); sending it with `proxyId` is rejected, as the
stored auth is used in the refetch flow.| +|url|string(uri)|false|none|Endpoint URL of the MCP server to fetch information from. Required unless
`proxyId` is given. When sent together with `proxyId` it overrides that proxy's
stored upstream URL, while the proxy's stored credentials are still used — this
validates an unsaved endpoint edit without re-sending a write-only secret.| +|proxyId|string|false|none|MCP proxy handle (identifier) for refresh operations. The stored credentials of
this proxy are used for the fetch, and its stored upstream URL too unless `url`
overrides it. Required unless `url` is given.| +|auth|[UpstreamAuth](#schemaupstreamauth)|false|none|Authentication configuration for the fetch request. Allowed only when `proxyId`
is absent (initial creation flow); sending it with `proxyId` is rejected, as the
stored auth is used whenever a proxy is referenced.| -oneOf +anyOf |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| |*anonymous*|object|false|none|none| -xor +or |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| @@ -5101,7 +5099,7 @@ not |Name|Type|Required|Restrictions|Description| |---|---|---|---|---| -|» *anonymous*|object|false|none|none| +|*anonymous*|object|false|none|none|

MCPServerInfoFetchResponse

diff --git a/event-gateway/gateway-controller/Makefile b/event-gateway/gateway-controller/Makefile index a55fa2aecd..17d4dfae48 100644 --- a/event-gateway/gateway-controller/Makefile +++ b/event-gateway/gateway-controller/Makefile @@ -29,7 +29,12 @@ IMAGE_NAME := $(DOCKER_REGISTRY)/event-gateway-controller # metadata, not compiled plugin code — unrelated to gateway/build.yaml). POLICIES_BUILD_CONTEXT ?= ../default-policies -.PHONY: help generate-server-code test build push build-and-push-multiarch build-coverage-image build-debug clean +# Doc generation +REPO_ROOT := $(shell git rev-parse --show-toplevel) +APIDOCS_TOOLS_DIR := $(REPO_ROOT)/tools/apidocs +DOCS_OUT_DIR := $(REPO_ROOT)/docs/rest-apis/event-gateway + +.PHONY: help generate-server-code generate-apidocs test build push build-and-push-multiarch build-coverage-image build-debug clean help: ## Show this help message @echo 'Usage: make [target]' @@ -41,6 +46,19 @@ generate-server-code: ## Generate WebSub/WebBroker API server code from OpenAPI @echo "Generating event-gateway API server code from OpenAPI spec..." @go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.5.1 --config=oapi-codegen.yaml api/eventgateway-openapi.yaml +generate-apidocs: ## Generate REST API docs (Markdown) from the Event Gateway OpenAPI spec + @command -v widdershins >/dev/null 2>&1 || { echo "widdershins not found, installing..."; npm install -g widdershins; } + @echo "Generating REST API docs..." + @set -e; \ + tmp_file=$$(mktemp "$${TMPDIR:-/tmp}/eventgateway-openapi.XXXXXX"); \ + trap 'rm -f "$$tmp_file"' EXIT; \ + widdershins api/eventgateway-openapi.yaml -o "$$tmp_file" \ + --omitHeader --summary \ + --language_tabs 'shell:Shell:curl' \ + --user_templates "$(APIDOCS_TOOLS_DIR)/widdershins_templates/"; \ + bash "$(APIDOCS_TOOLS_DIR)/split-openapi.sh" "$$tmp_file" "$(DOCS_OUT_DIR)" + @echo "REST API docs generated at $(DOCS_OUT_DIR)" + test: ## Run unit tests @echo "Running tests..." @go test -v ./... -cover -coverprofile=unit-test-coverage.txt