OpenAPI Specification for REST and Async APIs

[BLasan]

In the gateway controller there's only one endpoint to accept both REST and Async API imports. Hence the spec field should accept either APIConfigData or WebHookAPIData. To do this, there's a standard way introduced by openapi definition.

1. oneOf with discriminator

This approach only accepts either of objects defined under the schema based on a specific property. This way, there should be an unique property such as apiType to identify which object needs to be resolved during the runtime. This approach conflicts with the current api definition finalized[1][2].

2. anyOf

This validates any of the objects (one or more) at a given time. With respect to the API YAMLs accepted for different API types, there will be only one specific object per API.

[1] #369 (comment)
[2] https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/#anyof

Following is the sample openapi definition that is used by the codebase to process API Configuration files received.

openapi: 3.0.3
info:
  title: Gateway Controller API
  description: |
    REST API for managing API configurations in the WSO2 API Platform Gateway.

    The Gateway Controller accepts API configurations in YAML or JSON format and dynamically
    configures the Router (Envoy Proxy) via xDS protocol. Supports full CRUD lifecycle
    for API configurations with real-time updates to the Router.

    **Key Features:**
    - Submit API configurations in YAML or JSON
    - Real-time validation and error reporting
    - Zero-downtime configuration updates
    - Persistent storage with SQLite
    - Query deployed API configurations
  version: 1.0.0
  contact:
    name: WSO2 API Platform Team
servers:
  - url: http://localhost:9090
    description: Local development
  - url: http://gateway-controller:9090
    description: Docker/Kubernetes deployment

paths:
  /health:
    get:
      summary: Health check endpoint
      description: Returns the health status of the Gateway Controller
      operationId: healthCheck
      tags:
        - System
      responses:
        "200":
          description: Gateway Controller is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  timestamp:
                    type: string
                    format: date-time

  /apis:
    post:
      summary: Create a new API configuration
      description: |
        Submit a new API configuration to the Gateway Controller. The configuration
        is validated, persisted, and translated to Envoy xDS resources. The Router
        begins routing traffic for the API within 5 seconds.

        **Validation Rules:**
        - API name + version combination must be unique
        - Context must start with `/` and not end with `/`
        - At least one upstream and one operation required
        - For same API name, context must be consistent across versions
      operationId: createAPI
      tags:
        - API Management
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: "#/components/schemas/APIConfiguration"
            example:
              version: api-platform.wso2.com/v1
              kind: http/rest
              spec:
                name: PetStore API
                version: v1.0
                context: /petstore
                upstreams:
                  - url: http://petstore.swagger.io/v2
                policies:
                  - name: apiKeyValidation
                    version: v1.0.0
                    executionCondition: "request.metadata[authenticated] != true"
                    params:
                      header: X-API-Key
                      mandatory: true
                  - name: setHeaders
                    version: v1.0.0
                    params:
                      requestHeaders:
                        - X-Request-Source: WSO2 API Manager
                      responseHeaders:
                        - X-Response-Source: WSO2 API Manager
                operations:
                  - method: GET
                    path: /pet/{petId}
                    policies:
                      - name: apiKeyValidation
                        version: v1.0.0
                        executionCondition: "request.metadata[authenticated] != true"
                        params:
                          header: X-API-Key
                          mandatory: true
                  - method: POST
                    path: /pet
                  - method: PUT
                    path: /pet
                  - method: DELETE
                    path: /pet/{petId}
                  - method: GET
                    path: /store/inventory
                  - method: POST
                    path: /store/order
          application/json:
            schema:
              $ref: "#/components/schemas/APIConfiguration"
            example:
              version: api-platform.wso2.com/v1
              kind: http/rest
              spec:
                name: PetStore API
                version: v1.0
                context: /petstore
                upstreams:
                  - url: http://petstore.swagger.io/v2
                policies:
                  - name: apiKeyValidation
                    version: v1.0.0
                    executionCondition: "request.metadata[authenticated] != true"
                    params:
                      header: X-API-Key
                      mandatory: true
                  - name: setHeaders
                    version: v1.0.0
                    params:
                      requestHeaders:
                        - X-Request-Source: WSO2 API Manager
                      responseHeaders:
                        - X-Response-Source: WSO2 API Manager
                operations:
                  - method: GET
                    path: /pet/{petId}
                    policies:
                      - name: apiKeyValidation
                        version: v1.0.0
                        executionCondition: "request.metadata[authenticated] != true"
                        params:
                          header: X-API-Key
                          mandatory: true
                  - method: POST
                    path: /pet
                  - method: PUT
                    path: /pet
                  - method: DELETE
                    path: /pet/{petId}
                  - method: GET
                    path: /store/inventory
                  - method: POST
                    path: /store/order
      responses:
        "201":
          description: API configuration created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APICreateResponse"
        "400":
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflict - API with same name and version already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    get:
      summary: List all API configurations
      description: |
        Retrieve a list of all deployed API configurations with metadata.
        Returns basic information about each API (name, version, context, deployment time).
      operationId: listAPIs
      tags:
        - API Management
      responses:
        "200":
          description: List of API configurations
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                    example: 5
                  apis:
                    type: array
                    items:
                      $ref: "#/components/schemas/APIListItem"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /apis/{name}/{version}:
    get:
      summary: Get API configuration by name and version
      description: Retrieve the complete configuration for a specific API by its name and version
      operationId: getAPIByNameVersion
      tags:
        - API Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the API
          schema:
            type: string
          example: weather-api
        - name: version
          in: path
          required: true
          description: Version of the API
          schema:
            type: string
          example: v1.0
      responses:
        "200":
          description: API configuration details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIDetailResponse"
            application/yaml:
              schema:
                $ref: "#/components/schemas/APIDetailResponse"
        "404":
          description: API configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    put:
      summary: Update an existing API configuration
      description: |
        Update an existing API configuration. The update is validated and applied atomically.
        The Router receives the updated configuration within 5 seconds. In-flight requests
        complete with the old configuration; new requests use the updated configuration.

        **Important:** If validation fails, the existing configuration remains active.
      operationId: updateAPI
      tags:
        - API Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the API to update
          schema:
            type: string
          example: weather-api
        - name: version
          in: path
          required: true
          description: Version of the API to update
          schema:
            type: string
          example: v1.0
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: "#/components/schemas/APIConfiguration"
          application/json:
            schema:
              $ref: "#/components/schemas/APIConfiguration"
      responses:
        "200":
          description: API configuration updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIUpdateResponse"
        "400":
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: API configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Delete an API configuration
      description: |
        Remove an API configuration from the Gateway Controller. The Router stops
        accepting traffic for this API within 5 seconds. In-flight requests complete
        successfully; new requests receive 404 Not Found.
      operationId: deleteAPI
      tags:
        - API Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the API to delete
          schema:
            type: string
          example: weather-api
        - name: version
          in: path
          required: true
          description: Version of the API to delete
          schema:
            type: string
          example: v1.0
      responses:
        "200":
          description: API configuration deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: API configuration deleted successfully
                  id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
        "404":
          description: API configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /certificates:
    get:
      summary: List all custom certificates
      description: |
        Retrieve all custom TLS certificates currently loaded in the certificate store.
        These certificates are used for verifying HTTPS upstream connections.
      operationId: listCertificates
      tags:
        - Certificate Management
      responses:
        "200":
          description: List of certificates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateListResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      summary: Upload a new certificate
      description: |
        Upload a new custom TLS certificate to the certificate store. The certificate
        must be in PEM format. After upload, the certificate store is automatically
        reloaded and SDS (Secret Discovery Service) is updated to push the new
        certificate to Envoy proxies.

        **Dynamic Update:** Changes take effect immediately without restarting the gateway.
      operationId: uploadCertificate
      tags:
        - Certificate Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CertificateUploadRequest"
            example:
              name: my-custom-ca
              certificate: |
                -----BEGIN CERTIFICATE-----
                MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKtjMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
                ...
                -----END CERTIFICATE-----
      responses:
        "201":
          description: Certificate uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateResponse"
        "400":
          description: Invalid certificate format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /certificates/{id}:
    delete:
      summary: Delete a certificate
      description: |
        Delete a custom certificate by ID. After deletion, the certificate store
        is automatically reloaded and SDS is updated to remove the certificate from
        Envoy proxies.

        **Dynamic Update:** Changes take effect immediately without restarting the gateway.
      operationId: deleteCertificate
      tags:
        - Certificate Management
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the certificate to delete
          schema:
            type: string
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "200":
          description: Certificate deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Certificate deleted and SDS updated successfully
                  id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
        "404":
          description: Certificate not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /certificates/reload:
    post:
      summary: Manually reload certificates
      description: |
        Manually trigger a reload of all certificates from the filesystem and update
        SDS. This is useful if you've manually added certificate files to the
        certificates directory.

        **Note:** This endpoint is typically not needed as uploads and deletions
        automatically trigger reloads.
      operationId: reloadCertificates
      tags:
        - Certificate Management
      responses:
        "200":
          description: Certificates reloaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Certificates reloaded and SDS updated successfully
                  total_bytes:
                    type: integer
                    description: Total bytes of all loaded certificates
                    example: 221599
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /policies:
    get:
      summary: List all registered policy definitions
      description: |
        Retrieve all currently loaded policy definitions from the controller.
        Policy definitions are loaded from files in the policies directory at
        controller startup and stored in memory.
      operationId: listPolicies
      tags:
        - Policy Management
      responses:
        "200":
          description: List of policy definitions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyListResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /mcp-proxies:
    post:
      summary: Create a new MCP Proxy configuration
      description: |
        Submit a new MCP Proxy configuration to the Gateway Controller. The configuration
        is validated, persisted, and translated to Envoy xDS resources. The Router
        begins routing traffic for the MCP Proxy within 5 seconds.
      operationId: createMCPProxy
      tags:
        - MCP Proxy Management
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: "#/components/schemas/MCPProxyConfiguration"
          application/json:
            schema:
              $ref: "#/components/schemas/MCPProxyConfiguration"
      responses:
        "201":
          description: MCP Proxy configuration created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APICreateResponse"
        "400":
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflict - MCP Proxy with same name and version already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    get:
      summary: List all MCP Proxy configurations
      description: |
        Retrieve a list of all deployed MCP Proxy configurations with metadata.
        Returns basic information about each MCP Proxy (name, version, context, deployment time).
      operationId: listMCPProxies
      tags:
        - MCP Proxy Management
      responses:
        "200":
          description: List of MCP Proxy configurations
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                    example: 5
                  mcp_proxies:
                    type: array
                    items:
                      $ref: "#/components/schemas/MCPProxyListItem"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /mcp-proxies/{name}/{version}:
    get:
      summary: Get MCP Proxy configuration by name and version
      description: Retrieve the complete configuration for a specific MCP Proxy by its name and version
      operationId: getMCPProxyByNameVersion
      tags:
        - MCP Proxy Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the MCP Proxy
          schema:
            type: string
          example: mcp-proxy-1
        - name: version
          in: path
          required: true
          description: Version of the MCP Proxy
          schema:
            type: string
          example: v1.0
      responses:
        "200":
          description: MCP Proxy configuration details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MCPDetailResponse"
            application/yaml:
              schema:
                $ref: "#/components/schemas/MCPDetailResponse"
        "404":
          description: MCP Proxy configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    put:
      summary: Update an existing MCP Proxy configuration
      description: |
        Update an existing MCP Proxy configuration. The update is validated and applied atomically.
        The Router receives the updated configuration within 5 seconds. In-flight requests
        complete with the old configuration; new requests use the updated configuration.

        **Important:** If validation fails, the existing configuration remains active.
      operationId: updateMCPProxy
      tags:
        - MCP Proxy Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the MCP Proxy to update
          schema:
            type: string
          example: mcp-proxy-1
        - name: version
          in: path
          required: true
          description: Version of the MCP Proxy to update
          schema:
            type: string
          example: v1.0
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: "#/components/schemas/MCPProxyConfiguration"
          application/json:
            schema:
              $ref: "#/components/schemas/MCPProxyConfiguration"
      responses:
        "200":
          description: MCP Proxy configuration updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIUpdateResponse"
        "400":
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: MCP Proxy configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Delete an MCP Proxy configuration
      description: |
        Remove an MCP Proxy configuration from the Gateway Controller. The Router stops
        accepting traffic for this MCP Proxy within 5 seconds. In-flight requests complete
        successfully; new requests receive 404 Not Found.
      operationId: deleteMCPProxy
      tags:
        - MCP Proxy Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the MCP Proxy to delete
          schema:
            type: string
          example: mcp-proxy-1
        - name: version
          in: path
          required: true
          description: Version of the MCP Proxy to delete
          schema:
            type: string
          example: v1.0
      responses:
        "200":
          description: MCP Proxy configuration deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: MCP Proxy configuration deleted successfully
                  id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
        "404":
          description: MCP Proxy configuration not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /llm-provider-templates:
    post:
      summary: Create a new LLM provider template
      description: |
        Submit a new LLM provider template configuration. The template defines
        token tracking and model extraction related metadata.

        **Validation Rules:**
        - Template name must be unique
        - Token identifiers must use valid JSONPath expressions
      operationId: createLLMProviderTemplate
      tags:
        - LLM Provider Management
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/LLMProviderTemplate'
          application/json:
            schema:
              $ref: '#/components/schemas/LLMProviderTemplate'
      responses:
        '201':
          description: LLM provider template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderTemplateCreateResponse'
        '400':
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Template with same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      summary: List all LLM provider templates
      description: |
        Retrieve a list of all LLM provider templates.
      operationId: listLLMProviderTemplates
      tags:
        - LLM Provider Management
      responses:
        '200':
          description: List of LLM provider templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                    example: 3
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/LLMProviderTemplateListItem'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /llm-provider-templates/{name}:
    get:
      summary: Get LLM provider template by name
      description: Retrieve the complete configuration for a specific LLM provider template
      operationId: getLLMProviderTemplateByName
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the LLM provider template
          schema:
            type: string
          example: openai_v1.0
      responses:
        '200':
          description: LLM provider template details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderTemplateDetailResponse'
            application/yaml:
              schema:
                $ref: '#/components/schemas/LLMProviderTemplateDetailResponse'
        '404':
          description: LLM provider template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    put:
      summary: Update an existing LLM provider template
      description: |
        Update an existing LLM provider template configuration.
      operationId: updateLLMProviderTemplate
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the template to update
          schema:
            type: string
          example: openai_v1.0
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/LLMProviderTemplate'
          application/json:
            schema:
              $ref: '#/components/schemas/LLMProviderTemplate'
      responses:
        '200':
          description: LLM provider template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderTemplateUpdateResponse'
        '400':
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: LLM provider template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete an LLM provider template
      description: |
        Remove an LLM provider template from the Gateway Controller.
      operationId: deleteLLMProviderTemplate
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the template to delete
          schema:
            type: string
          example: openai_v1.0
      responses:
        '200':
          description: LLM provider template deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: LLM provider template deleted successfully
                  id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
        '404':
          description: LLM provider template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /llm-providers:
    post:
      summary: Create a new LLM provider
      description: |
        Deploy a new LLM provider configuration. The provider defines how to interact
        with an LLM service, including upstream endpoints, authentication, access control,
        and policies.
      operationId: createLLMProvider
      tags:
        - LLM Provider Management
      requestBody:
        required: true
        description: LLM provider configuration in YAML or JSON format
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/LLMProviderConfiguration'
          application/json:
            schema:
              $ref: '#/components/schemas/LLMProviderConfiguration'
      responses:
        '201':
          description: LLM provider created and deployed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderCreateResponse'
        '400':
          description: Invalid configuration (validation failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Provider with same name and version already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      summary: List all LLM providers
      description: Retrieve a list of all LLM providers
      operationId: listLLMProviders
      tags:
        - LLM Provider Management
      responses:
        '200':
          description: List of LLM providers
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                    example: 2
                  providers:
                    type: array
                    items:
                      $ref: '#/components/schemas/LLMProviderListItem'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /llm-providers/{name}/{version}:
    get:
      summary: Get LLM provider by name and version
      description: Retrieve the complete configuration for a specific LLM provider
      operationId: getLLMProviderByNameVersion
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the LLM provider
          schema:
            type: string
          example: wso2-openai-provider
        - name: version
          in: path
          required: true
          description: Version of the LLM provider
          schema:
            type: string
          example: v1.0
      responses:
        '200':
          description: LLM provider details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderDetailResponse'
            application/yaml:
              schema:
                $ref: '#/components/schemas/LLMProviderDetailResponse'
        '404':
          description: LLM provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    put:
      summary: Update an existing LLM provider
      description: Update the configuration of an existing LLM provider
      operationId: updateLLMProvider
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the LLM provider
          schema:
            type: string
          example: wso2-openai-provider
        - name: version
          in: path
          required: true
          description: Version of the LLM provider
          schema:
            type: string
          example: v1.0
      requestBody:
        required: true
        description: Updated LLM provider configuration
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/LLMProviderConfiguration'
          application/json:
            schema:
              $ref: '#/components/schemas/LLMProviderConfiguration'
      responses:
        '200':
          description: LLM provider updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMProviderUpdateResponse'
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: LLM provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete an LLM provider
      description: Remove an LLM provider from the Gateway Controller
      operationId: deleteLLMProvider
      tags:
        - LLM Provider Management
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the LLM provider
          schema:
            type: string
          example: wso2-openai-provider
        - name: version
          in: path
          required: true
          description: Version of the LLM provider
          schema:
            type: string
          example: v1.0
      responses:
        '200':
          description: LLM provider deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: LLM provider deleted successfully
                  id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
        '404':
          description: LLM provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /config_dump:
    get:
      summary: Dump current configuration state
      description: |
        Retrieve the complete current state of the Gateway Controller including:
        - All deployed API configurations
        - All loaded policy definitions
        - All registered certificates
        - System status and metadata

        This endpoint is useful for debugging, monitoring, and backup purposes.
      operationId: getConfigDump
      tags:
        - System
      responses:
        "200":
          description: Complete configuration dump
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigDumpResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    APIConfiguration:
      type: object
      required:
        - version
        - kind
        - spec
      properties:
        version:
          type: string
          description: API specification version
          example: api-platform.wso2.com/v1
          enum:
            - api-platform.wso2.com/v1
        kind:
          type: string
          description: API type
          example: http/rest
          enum:
            - http/rest
            - async/websub
            - async/websocket
            - async/sse
        spec:
          description: API configuration payload (REST or Async API variants)
          anyOf:
            - $ref: '#/components/schemas/APIConfigData'
            - $ref: '#/components/schemas/WebhookAPIData'

    APIConfigData:
      type: object
      required:
        - name
        - version
        - context
        - upstreams
        - operations
      properties:
        name:
          type: string
          description: Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
          minLength: 1
          maxLength: 100
          pattern: '^[a-zA-Z0-9\-_\. ]+$'
          example: weather-api
        version:
          type: string
          description: Semantic version of the API
          pattern: '^v\d+\.\d+$'
          example: v1.0
        context:
          type: string
          description: Base path for all API routes (must start with /, no trailing slash)
          pattern: '^\/[a-zA-Z0-9_\-\/]*[^\/]$'
          minLength: 1
          maxLength: 200
          example: /weather
        upstreams:
          type: array
          description: List of backend service URLs
          minItems: 1
          items:
            $ref: "#/components/schemas/Upstream"
        policies:
          type: array
          description: List of API-level policies applied to all operations unless overridden
          items:
            $ref: "#/components/schemas/Policy"
        operations:
          type: array
          description: List of HTTP operations/routes
          minItems: 1
          items:
            $ref: "#/components/schemas/Operation"

    Upstream:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Backend service URL (may include path prefix like /api/v2)
          example: https://api.weather.com/api/v2

    Operation:
      type: object
      required:
        - method
        - path
      properties:
        method:
          type: string
          description: HTTP method
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - PATCH
            - HEAD
            - OPTIONS
          example: GET
        path:
          type: string
          description: Route path with optional {param} placeholders
          pattern: '^\/.*$'
          example: /{country_code}/{city}
        policies:
          type: array
          description: List of policies applied only to this operation (overrides or adds to API-level policies)
          items:
            $ref: "#/components/schemas/Policy"

    Policy:
      type: object
      required:
        - name
        - version
      properties:
        name:
          type: string
          description: Name of the policy
          example: apiKeyValidation
        version:
          type: string
          description: Semantic version of the policy
          pattern: '^v\d+\.\d+\.\d+$'
          example: v1.0.0
        executionCondition:
          type: string
          description: Expression controlling conditional execution of the policy
          example: "request.metadata[authenticated] != true"
        params:
          type: object
          description: Arbitrary parameters for the policy (free-form key/value structure)
          additionalProperties: true
    # Reusable policy definition (catalog entry)
    PolicyDefinition:
      type: object
      required:
        - name
        - version
        - flows
      properties:
        name:
          type: string
          description: Unique policy name
          minLength: 1
          maxLength: 200
          example: APIKeyValidation
        version:
          type: string
          description: Semantic version of the policy definition
          pattern: '^v\d+\.\d+\.\d+$'
          example: v1.0.0
        description:
          type: string
          description: Human readable description of the policy's purpose
          maxLength: 2000
        parameters:
          type: object
          description: JSON Schema describing the parameters accepted by this policy. This itself is a JSON Schema document.
          additionalProperties: true
        initParameters:
          type: object
          description: JSON Schema describing any initialization parameters for this policy. This itself is a JSON Schema document.
          additionalProperties: true

    PolicyListResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        count:
          type: integer
          example: 2
        policies:
          type: array
          items:
            $ref: "#/components/schemas/PolicyDefinition"

    # -----------------------
    # Webhook (Async) API schema
    # -----------------------
    WebhookAPIData:
      type: object
      required:
        - name
        - version
        - context
        - servers
        - channels
      properties:
        name:
          type: string
          description: Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
          minLength: 1
          maxLength: 100
          pattern: '^[a-zA-Z0-9\-_\. ]+$'
          example: weather-api
        version:
          type: string
          description: Semantic version of the API
          pattern: '^v\d+\.\d+$'
          example: v1.0
        context:
          type: string
          description: Base path for all API routes (must start with /, no trailing slash)
          pattern: '^\/[a-zA-Z0-9_\-\/]*[^\/]$'
          minLength: 1
          maxLength: 200
          example: /weather
        servers:
          type: array
          description: List of backend service URLs (for REST APIs) or event hub URLs (for async APIs)
          minItems: 1
          items:
            $ref: '#/components/schemas/Server'
        channels:
          type: array
          description: List of operations - HTTP operations for REST APIs or event/topic operations for async APIs
          minItems: 1
          items:
            $ref: '#/components/schemas/Channel'
        policies:
          type: array
          description: List of API-level policies applied to all operations unless overridden
          items:
            $ref: '#/components/schemas/Policy'

    # AsyncAPI-inspired server definition used when kind is async/* or http/websub.
    # Simplified mapping of AsyncAPI 2.x Server Object into OpenAPI.
    Server:
      type: object
      description: Server definition for async or WebSub APIs.
      required:
        - url
        - protocol
      properties:
        url:
          type: string
          format: uri
          description: Base URL or connection string for the server (variables may be denoted by {name}).
          example: https://websub-hub.internal:9098
        protocol:
          type: string
          description: Transport protocol used by the server.
          enum:
            - websub
            - websocket
            - sse
            - mqtt
            - kafka
          example: websub
        protocolVersion:
          type: string
          description: Version of the selected protocol (if applicable).
          example: '1.0'
        description:
          type: string
          description: Human-readable description of this server.
          example: Internal WebSub Hub instance.
        variables:
          type: object
          description: Templated variables contained in the server URL.
          additionalProperties:
            type: object
            required:
              - default
            properties:
              enum:
                type: array
                items:
                  type: string
                description: Allowed values.
              default:
                type: string
                description: Default value for the variable.
              description:
                type: string
                description: Description of the variable.
        security:
          type: array
          description: Security requirements for this server (each item maps scheme name to optional scopes array).
          items:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
        bindings:
          type: object
          description: Protocol-specific server bindings (arbitrary key/value structure).
          additionalProperties: true

    # Simplified AsyncAPI Channel object represented as an OpenAPI schema.
    Channel:
      type: object
      description: Channel (topic/event stream) definition for async APIs.
      required:
        - path
      properties:
        path:
          type: string
          description: Channel path or topic identifier relative to API context.
          example: /issues
        description:
          type: string
          description: Human-readable description of the channel.
          example: GitHub issue events channel.
        subscribe:
          type: object
          description: Consumer (receive) operation definition.
          properties:
            summary:
              type: string
              example: Receive issue events.
            message:
              $ref: '#/components/schemas/ChannelMessage'
        publish:
          type: object
          description: Producer (send) operation definition.
          properties:
            summary:
              type: string
              example: Publish issue events.
            message:
              $ref: '#/components/schemas/ChannelMessage'
        parameters:
          type: object
          description: Path/channel parameters (keyed by parameter name).
          additionalProperties:
            type: object
            properties:
              description:
                type: string
              schema:
                type: object
                description: JSON Schema fragment for the parameter value.
                additionalProperties: true
        bindings:
          type: object
          description: Protocol-specific channel bindings (arbitrary key/value structure).
          additionalProperties: true
        policies:
          type: array
          description: List of policies applied only to this operation (overrides or adds to API-level policies)
          items:
            $ref: '#/components/schemas/Policy'

    # Message schema used within Channel publish/subscribe operations.
    ChannelMessage:
      type: object
      description: Event/message definition transported over a channel.
      required:
        - name
        - payload
      properties:
        name:
          type: string
          description: Logical message name.
          example: IssueEvent
        content_type:
          type: string
          description: Content type of the payload.
          example: application/json
        summary:
          type: string
          description: Short description of the message.
          example: Event emitted when an issue is created.
        payload:
          type: object
          description: JSON Schema representation of the message body.
          additionalProperties: true
          example:
            type: object
            properties:
              action:
                type: string
              issue:
                type: object

    APICreateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: API configuration created successfully
        id:
          type: string
          format: uuid
          description: Unique identifier for the created API configuration
          example: 550e8400-e29b-41d4-a716-446655440000
        created_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z
    APIUpdateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: API configuration updated successfully
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        updated_at:
          type: string
          format: date-time
          example: 2025-10-11T11:45:00Z

    APIListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: weather-api
        version:
          type: string
          example: v1.0
        context:
          type: string
          example: /weather
        status:
          type: string
          enum:
            - pending
            - deployed
            - failed
          example: deployed
        created_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z

    APIDetailResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        api:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            configuration:
              $ref: "#/components/schemas/APIConfiguration"
            metadata:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - pending
                    - deployed
                    - failed
                  example: deployed
                created_at:
                  type: string
                  format: date-time
                  example: 2025-10-11T10:30:00Z
                updated_at:
                  type: string
                  format: date-time
                  example: 2025-10-11T10:30:00Z
                deployed_at:
                  type: string
                  format: date-time
                  example: 2025-10-11T10:30:05Z

    MCPProxyConfiguration:
      type: object
      required:
        - version
        - kind
        - spec
      properties:
        version:
          type: string
          description: MCP Proxy specification version
          example: ai.api-platform.wso2.com/v1
          enum:
            - ai.api-platform.wso2.com/v1
        kind:
          type: string
          description: MCP Proxy type
          example: mcp
          enum:
            - mcp
        spec:
          $ref: "#/components/schemas/MCPProxyConfigData"

    MCPProxyConfigData:
      type: object
      required:
        - name
        - version
        - context
        - upstreams
      properties:
        name:
          type: string
          description: Human-readable MCP Proxy name
          minLength: 1
          maxLength: 100
          pattern: '^[a-zA-Z0-9\-_\. ]+$'
          example: mcp-proxy-1
        version:
          type: string
          description: MCP Proxy version
          example: v1.0
        context:
          type: string
          description: MCP Proxy context path
          example: /mcp-proxy
        specVersion:
          type: string
          description: MCP specification version
          example: 2025-06-18
        upstreams:
          type: array
          description: List of backend service URLs
          minItems: 1
          items:
            $ref: "#/components/schemas/Upstream"
        tools:
          type: array
          items:
            $ref: "#/components/schemas/MCPTool"
        resources:
          type: array
          items:
            $ref: "#/components/schemas/MCPResource"
        prompts:
          type: array
          items:
            $ref: "#/components/schemas/MCPPrompt"

    MCPTool:
      type: object
      required:
        - name
        - description
        - inputSchema
      properties:
        name:
          type: string
          description: Unique identifier for the tool
        title:
          type: string
          description: Optional human-readable name of the tool for display purposes.
        description:
          type: string
          description: Human-readable description of functionality
        inputSchema:
          type: string
          description: JSON Schema defining expected parameters
        outputSchema:
          type: string
          description: Optional JSON Schema defining expected output structure

    MCPResource:
      type: object
      required:
        - uri
        - name
      properties:
        uri:
          type: string
          description: Unique identifier for the resource
        name:
          type: string
          description: The name of the resource
        title:
          type: string
          description: Optional human-readable name of the resource for display purposes
        description:
          type: string
          description: Optional description
        mimeType:
          type: string
          description: Optional MIME type
        size:
          type: integer
          description: Optional size in bytes

    MCPPrompt:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Unique identifier for the prompt
        title:
          type: string
          description: Optional human-readable name of the prompt for display purposes
        description:
          type: string
          description: Optional human-readable description
        arguments:
          type: array
          description: Optional list of arguments for customization
          items:
            type: object
            required:
              - name
            properties:
              name:
                type: string
                description: Name of the argument
              description:
                type: string
                description: Description of the argument
              required:
                type: boolean
                description: Whether the argument is required
              title:
                type: string
                description: Optional human-readable title of the argument

    MCPProxyListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: mcp-proxy-1
        version:
          type: string
          example: v1.0
        context:
          type: string
          example: /mcp-proxy
        specVersion:
          type: string
          example: 2025-06-18
        status:
          type: string
          enum:
            - pending
            - deployed
            - failed
          example: deployed
        created_at:
          type: string
          format: date-time
          example: 2025-11-24T10:30:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-11-24T10:30:00Z

    MCPDetailResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        mcp:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            configuration:
              $ref: "#/components/schemas/MCPProxyConfiguration"
            metadata:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - pending
                    - deployed
                    - failed
                  example: deployed
                created_at:
                  type: string
                  format: date-time
                  example: 2025-11-24T10:30:00Z
                updated_at:
                  type: string
                  format: date-time
                  example: 2025-11-24T10:30:00Z
                deployed_at:
                  type: string
                  format: date-time
                  example: 2025-11-24T10:30:05Z

    ErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: High-level error description
          example: Configuration validation failed
        errors:
          type: array
          description: Detailed validation errors
          items:
            $ref: "#/components/schemas/ValidationError"

    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: spec.context
        message:
          type: string
          description: Human-readable error message
          example: Context must start with / and cannot end with /

    LLMProviderTemplate:
      type: object
      required:
        - version
        - kind
        - spec
      properties:
        version:
          type: string
          description: Template specification version
          example: ai.api-platform.wso2.com/v1
          enum:
            - ai.api-platform.wso2.com/v1
        kind:
          type: string
          description: Template kind
          example: llm/provider-template
          enum:
            - llm/provider-template
        spec:
          $ref: '#/components/schemas/LLMProviderTemplateData'

    LLMProviderTemplateData:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Unique name for the provider template
          example: openai_v1.0
        promptTokens:
          $ref: '#/components/schemas/ExtractionIdentifier'
        completionTokens:
          $ref: '#/components/schemas/ExtractionIdentifier'
        totalTokens:
          $ref: '#/components/schemas/ExtractionIdentifier'
        requestModel:
          $ref: '#/components/schemas/ExtractionIdentifier'

    ExtractionIdentifier:
      type: object
      required:
        - location
        - identifier
      properties:
        location:
          type: string
          description: Where to find the token information
          enum:
            - payload
            - header
          example: payload
        identifier:
          type: string
          description: JSONPath expression or header name to identify the token value
          example: $.usage.inputTokens

    LLMProviderTemplateCreateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: LLM provider template created successfully
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        created_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z

    LLMProviderTemplateUpdateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: LLM provider template updated successfully
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        updated_at:
          type: string
          format: date-time
          example: 2025-10-11T11:45:00Z

    LLMProviderTemplateListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: openai_v1.0
        created_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-10-11T10:30:00Z

    LLMProviderTemplateDetailResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        template:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            configuration:
              $ref: '#/components/schemas/LLMProviderTemplate'
            metadata:
              type: object
              properties:
                created_at:
                  type: string
                  format: date-time
                  example: 2025-10-11T10:30:00Z
                updated_at:
                  type: string
                  format: date-time
                  example: 2025-10-11T10:30:00Z

    LLMProviderCreateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: LLM provider created successfully
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        created_at:
          type: string
          format: date-time
          example: 2025-11-25T10:30:00Z

    LLMProviderUpdateResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: LLM provider updated successfully
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        updated_at:
          type: string
          format: date-time
          example: 2025-11-25T11:45:00Z

    LLMProviderListItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: wso2-openai-provider
        version:
          type: string
          example: v1.0
        template:
          type: string
          example: openai_v1.0
        status:
          type: string
          enum:
            - pending
            - deployed
            - failed
          example: deployed
        created_at:
          type: string
          format: date-time
          example: 2025-11-25T10:30:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-11-25T10:30:00Z

    LLMProviderDetailResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        provider:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 550e8400-e29b-41d4-a716-446655440000
            configuration:
              $ref: '#/components/schemas/LLMProviderConfiguration'
            deployment_status:
              type: string
              enum:
                - pending
                - deployed
                - failed
              example: deployed
            metadata:
              type: object
              properties:
                created_at:
                  type: string
                  format: date-time
                  example: 2025-11-25T10:30:00Z
                updated_at:
                  type: string
                  format: date-time
                  example: 2025-11-25T10:30:00Z
                deployed_at:
                  type: string
                  format: date-time
                  example: 2025-11-25T10:35:00Z

    LLMProviderConfiguration:
      type: object
      required:
        - version
        - kind
        - spec
      properties:
        version:
          type: string
          description: Provider specification version
          example: ai.api-platform.wso2.com/v1
          enum:
            - ai.api-platform.wso2.com/v1
        kind:
          type: string
          description: Provider kind
          example: llm/provider
          enum:
            - llm/provider
        spec:
          $ref: '#/components/schemas/LLMProviderConfigData'

    LLMProviderConfigData:
      type: object
      required:
        - name
        - version
        - template
        - upstreams
        - accessControl
      properties:
        name:
          type: string
          description: Human-readable LLM Provider name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
          minLength: 1
          maxLength: 100
          pattern: '^[a-zA-Z0-9\-_\. ]+$'
          example: wso2-openai-provider
        version:
          type: string
          description: Semantic version of the LLM Provider
          pattern: '^v\d+\.\d+$'
          example: v1.0
        context:
          type: string
          description: Base path for all API routes (must start with /, no trailing slash)
          pattern: '^\/([a-zA-Z0-9_\-\/]*[^\/])?$'
          default: /
          minLength: 1
          maxLength: 200
          example: /openai
        host:
          type: string
          description: >
            Virtual host name used for routing. Supports standard domain names,
            subdomains, or wildcard domains. Must follow RFC-compliant hostname
            rules. Wildcards are only allowed in the left-most label (e.g., *.example.com).
          pattern: '^(\*\.|[a-zA-Z0-9](?:[a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$'
          minLength: 1
          maxLength: 253
          example: "api.openai"
        template:
          type: string
          description: Template name to use for this LLM Provider
          example: openai_v1.0
        upstreams:
          type: array
          description: List of backend service URLs
          minItems: 1
          items:
            $ref: "#/components/schemas/UpstreamWithAuth"
        accessControl:
          $ref: '#/components/schemas/LLMAccessControl'
        policies:
          type: array
          description: List of policies applied only to this operation (overrides or adds to API-level policies)
          items:
            $ref: "#/components/schemas/LLMPolicy"

    UpstreamAuth:
      type: object
      properties:
        auth:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum: [ api-key, bearer ]
            header:
              type: string
            value:
              type: string

    UpstreamWithAuth:
      allOf:
        - $ref: '#/components/schemas/Upstream'
        - $ref: '#/components/schemas/UpstreamAuth'

    LLMAccessControl:
      type: object
      required:
        - mode
      properties:
        mode:
          type: string
          description: Access control mode
          example: deny_all
          enum:
            - allow_all
            - deny_all
        exceptions:
          type: array
          description: Path exceptions to the access control mode
          items:
            $ref: '#/components/schemas/RouteException'

    RouteException:
      type: object
      required:
        - path
        - methods
      properties:
        path:
          type: string
          description: Path pattern
          example: /chat/completions
        methods:
          type: array
          description: HTTP methods
          items:
            type: string
            enum:
              - GET
              - POST
              - PUT
              - DELETE
              - PATCH

    LLMPolicy:
      type: object
      required:
        - name
        - version
        - paths
      properties:
        name:
          type: string
          example: budgetControl
        version:
          type: string
          example: v1.0.0
        paths:
          type: array
          items:
            $ref: '#/components/schemas/LLMPolicyPath'

    LLMPolicyPath:
      type: object
      required:
        - path
        - methods
        - params
      properties:
        path:
          type: string
          example: /chat/completions
        methods:
          type: array
          items:
            type: string
            enum: [ GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD ]
        params:
          type: object
          description: JSON Schema describing the parameters accepted by this policy. This itself is a JSON Schema document.
          additionalProperties: true

    CertificateUploadRequest:
      type: object
      required:
        - certificate
        - name
      properties:
        name:
          type: string
          description: Unique name for the certificate. Must be unique across all certificates.
          pattern: "^[a-zA-Z0-9._-]+$"
          minLength: 1
          maxLength: 100
          example: my-custom-ca
        certificate:
          type: string
          description: PEM-encoded X.509 certificate(s). Can contain multiple certificates.
          example: |
            -----BEGIN CERTIFICATE-----
            MIIDXTCCAkWgAwIBAgIJAKL0UG+mRKtjMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
            ...
            -----END CERTIFICATE-----

    CertificateResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (UUID) for the certificate
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Name of the certificate
          example: my-custom-ca
        subject:
          type: string
          description: Certificate subject DN (for first cert if bundle)
          example: CN=My CA,O=My Organization,C=US
        issuer:
          type: string
          description: Certificate issuer DN (for first cert if bundle)
          example: CN=My CA,O=My Organization,C=US
        notAfter:
          type: string
          description: Certificate expiration date (for first cert if bundle)
          format: date-time
          example: "2026-11-26 06:07:26"
        count:
          type: integer
          description: Number of certificates in the file
          example: 1
        message:
          type: string
          description: Success or informational message
          example: Certificate uploaded and SDS updated successfully
        status:
          type: string
          enum: [success, error]
          example: success

    CertificateListResponse:
      type: object
      properties:
        certificates:
          type: array
          items:
            $ref: "#/components/schemas/CertificateResponse"
        totalCount:
          type: integer
          description: Total number of certificate files
          example: 3
        totalBytes:
          type: integer
          description: Total bytes of all certificate files
          example: 221599
        status:
          type: string
          example: success

    ConfigDumpResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the config dump was generated
          example: "2025-11-26T10:30:00Z"
        apis:
          type: array
          description: All deployed API configurations
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                example: 550e8400-e29b-41d4-a716-446655440000
              configuration:
                $ref: "#/components/schemas/APIConfiguration"
              metadata:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - pending
                      - deployed
                      - failed
                    example: deployed
                  created_at:
                    type: string
                    format: date-time
                    example: 2025-10-11T10:30:00Z
                  updated_at:
                    type: string
                    format: date-time
                    example: 2025-10-11T10:30:00Z
                  deployed_at:
                    type: string
                    format: date-time
                    example: 2025-10-11T10:30:05Z
        policies:
          type: array
          description: All loaded policy definitions
          items:
            $ref: "#/components/schemas/PolicyDefinition"
        certificates:
          type: array
          description: All registered certificates
          items:
            $ref: "#/components/schemas/CertificateResponse"
        statistics:
          type: object
          description: Summary statistics about the current configuration
          properties:
            totalApis:
              type: integer
              description: Total number of API configurations
              example: 5
            totalPolicies:
              type: integer
              description: Total number of policy definitions
              example: 3
            totalCertificates:
              type: integer
              description: Total number of certificates
              example: 2
            totalCertificateBytes:
              type: integer
              description: Total bytes of all certificates
              example: 221599

tags:
  - name: System
    description: System health and status endpoints
  - name: API Management
    description: CRUD operations for API configurations
  - name: MCP Proxy Management
    description: CRUD operations for MCP Proxy configurations
  - name: Policy Management
    description: Registration of reusable policy definitions
  - name: Certificate Management
    description: Manage custom TLS certificates for HTTPS upstream verification

[BLasan]

@renuka-fernando @pubudu538 Any thoughts on this? This needs to be finalized soon as this could break the existing functionalities if changed continuously.

[BLasan]

version: api-platform.wso2.com/v1
kind: async/websub
metaData:
   name: WebSubHub-API
spec:
  name: WebSub-API-New-API
  version: v1.0
  context: /websubnewapi
  vhosts:
    main:
      default: "*"
    sandbox:
      default: "sandbox-*"
  upstream:
      main:
       url: http://host.docker.internal:9098
      sandbox:
       url: http://host.docker.internal:9098
  channels:
    -  path: /pull-requests
       subscribe:
        policies:
          - name: ModifyHeaders
            version: v1.0.0
            enabled: true
            params:
              requestHeaders:
                - action: SET
                  name: operation-level-req-header
                  value: hello
              responseHeaders:
                - action: SET
                  name: operation-level-res-header
                  value: world
    -  path: /issues
       subscribe:
         policies:
          - name: ModifyHeaders
            version: v1.0.0
            enabled: true
            params:
              requestHeaders:
                - action: SET
                  name: operation-level-req-header
                  value: hello
              responseHeaders:
                - action: SET
                  name: operation-level-res-header
                  value: world

[nuwand]

I don't really understand the problem being discussed here. There is a massive spec file (or something) provided but I'm not sure where to look at.

Can you explain the problem in simpler terms please?