openapi: 3.0.1
info:
  description: |
    **This file forms part of Mplify 147**

    **This API implements part of the Business Requirements & Use Cases described 
    in Mplify 133.1 section 12.**

    List of use cases supported by Performance Monitoring Data Streaming Management API: 
    - List Available Topics for Subscription
    - List Subscribed Topics
    - Subscribe to a Topic
    - Unsubscribe from a Topic


    Most important entities supported by the API:
    - **Topic** - metadata describing a topic available for subscription

    - **Subscription** - contains metadata information describing a data stream that provides the details allowing for data consumption

    This API uses by reference AsyncAPI v2.6.0 models.

    Copyright 2025 Mplify Alliance and its contributors

  title: Streaming Management
  version: 1.0.0
servers:
  - url: 'https://{serverBase}/mefApi/legato/streamingManagement/v1'
    variables:
      serverBase:
        default: mplify.net
        description: The base of SOF's URL.
tags:
  - description: Groups all operations related to the available topic.
    name: topic
  - description: |
      Groups all operations related to subscribed topics and  subscription management.
    name: subscription
  - name: events subscription
paths:
  /topic:
    get:
      description:
        List topics available for subscription to performance monitoring data
      operationId: topicList
      parameters:
        - description: Category of the available topic
          in: query
          name: category
          required: false
          schema:
            type: string
        - description:
            A communication protocol supported by the available topic
          in: query
          name: protocol
          required: false
          schema:
            type: string
        - description:
            Requested number of elements to be provided in response requested
            by client
          in: query
          name: limit
          required: false
          schema:
            format: int32
            type: integer
        - description:
            Requested index for the start of elements to be provided in
            response requested by the client. Note that the index starts with
            "0".
          in: query
          name: offset
          required: false
          schema:
            format: int32
            type: integer
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Topic'
                type: array
          description: Success
          headers:
            X-Pagination-Throttled:
              description: |
                Used to indicate that the result page was throttled to a maximum possible size  and there are additional results that can be fetched
              schema:
                type: boolean
            X-Result-Count:
              description: |
                Actual number of items returned in the response body E.g. if there are 50 matching items in total,  but the request has offset=10 and limit=10, then the X-Total-Count is 50.
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items included in the response
              schema:
                type: integer
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Retrieve Available Topics
      tags:
        - topic
  /topic/{id}:
    get:
      description: Information about the topic available for subscription
      operationId: topicById
      parameters:
        - description: Identifier of the topic
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Topic'
          description: Success
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '404':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
          description: Not Found
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Retrieve Available Topic by an Identifier
      tags:
        - topic
  /subscription:
    get:
      description: List all the subscriptions to all the topics
      operationId: subscriptionList
      parameters:
        - description: Identifier of a topic subscription belongs to
          in: query
          name: topicId
          required: false
          schema:
            type: string
        - description:
            A communication protocol supported by the available topic
          in: query
          name: protocol
          required: false
          schema:
            type: string
        - description:
            Requested number of elements to be provided in response requested
            by client
          in: query
          name: limit
          required: false
          schema:
            format: int32
            type: integer
        - description:
            Requested index for the start of elements to be provided in
            response requested by the client. Note that the index starts with
            "0".
          in: query
          name: offset
          required: false
          schema:
            format: int32
            type: integer
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/TopicSubscription'
                type: array
            application/vnd.aai.asyncapi+json:
              schema:
                $ref: '#/components/schemas/AsyncAPIModel'
          description: Success
          headers:
            X-Pagination-Throttled:
              description: |
                Used to indicate that the result page was throttled to the maximum possible size  and there are additional results that can be fetched
              schema:
                type: boolean
            X-Result-Count:
              description: |
                An actual number of items returned in the response body E.g. if there are 50 matching items in total,  but the request has offset=10 and limit=10, then the X-Total-Count is 50.
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items included in the response
              schema:
                type: integer
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Retrieve Topic Subscriptions List
      tags:
        - subscription
    post:
      description: Subscribe to the selected topic
      operationId: subscribeTopic
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/TopicSubscriptionRequest'
      responses:
        '201':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/TopicSubscription'
          description: Registered
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '422':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Error422'
                type: array
          description:
            Unprocessable entity due to the business validation problems
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Subscribe To a Topic
      tags:
        - subscription
  /subscription/{id}:
    delete:
      description: Remove a subscription for a  topic
      operationId: unsubscribeTopic
      parameters:
        - description: Identifier of the subscription
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Unsubscribe operation successful
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '404':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
          description: Not Found
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Unsubscribe From a Topic
      tags:
        - subscription
    get:
      description: Retrieve information about a subscription to a topic
      operationId: subscriptionById
      parameters:
        - description: Identifier of the subscription
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/TopicSubscription'
          description: Success
        '400':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
          description: Bad Request
        '401':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
          description: Unauthorized
        '403':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
          description: Forbidden
        '404':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error404'
          description: Not Found
        '405':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
          description: Method Not Allowed
        '500':
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
          description: Internal Server Error
      summary: Retrieve Topic Subscription By an Identifier
      tags:
        - subscription
components:
  parameters:
    Offset:
      description:
        Requested index for the start of elements to be provided in response
        requested by the client. Note that the index starts with "0".
      in: query
      name: offset
      required: false
      schema:
        format: int32
        type: integer
    Limit:
      description:
        Requested number of elements to be provided in response requested by
        client
      in: query
      name: limit
      required: false
      schema:
        format: int32
        type: integer
  responses:
    '400':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error400'
      description: Bad Request
    '401':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error401'
      description: Unauthorized
    '403':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error403'
      description: Forbidden
    '404':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error404'
      description: Not Found
    '405':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error'
      description: Method Not Allowed
    '422':
      content:
        application/json;charset=utf-8:
          schema:
            items:
              $ref: '#/components/schemas/Error422'
            type: array
      description: Unprocessable entity due to the business validation problems
    '500':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error500'
      description: Internal Server Error
  schemas:
    AsyncAPIModel:
      $ref: 'http://asyncapi.com/definitions/2.6.0/asyncapi.json'
    Error:
      description:
        Standard Class used to describe API response error Not intended to be
        used directly. The `code` in the HTTP header is used as a discriminator
        for the type of error returned in runtime.
      properties:
        message:
          description:
            Text that provides mode details and corrective actions related to
            the error. This can be shown to a client user.
          type: string
        reason:
          description:
            Text that explains the reason for the error. This can be shown to a
            client user.
          maxLength: 255
          type: string
        referenceError:
          description: URL pointing to documentation describing the error
          format: uri
          type: string
      required:
        - reason
      type: object
    Error400:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error400Code'
          required:
            - code
          type: object
      description:
        Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)
    Error400Code:
      description: |-
        One of the following error codes:
        - missingQueryParameter: The URI is missing a required query-string parameter
        - missingQueryValue: The URI is missing a required query-string parameter value
        - invalidQuery: The query section of the URI is invalid.
        - invalidBody: The request has an invalid body
      enum:
        - missingQueryParameter
        - missingQueryValue
        - invalidQuery
        - invalidBody
      type: string
    Error401:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error401Code'
          required:
            - code
          type: object
      description:
        Unauthorized.  (https://tools.ietf.org/html/rfc7235#section-3.1)
    Error401Code:
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      enum:
        - missingCredentials
        - invalidCredentials
      type: string
    Error403:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error403Code'
          required:
            - code
          type: object
      description:
        Forbidden. This code indicates that the server understood the request
        but refuses to authorize it.
        (https://tools.ietf.org/html/rfc7231#section-6.5.3)
    Error403Code:
      description: |-
        This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes:
        - accessDenied: Access denied
        - forbiddenRequester: Forbidden requester
        - tooManyUsers: Too many users
      enum:
        - accessDenied
        - forbiddenRequester
        - tooManyUsers
      type: string
    Error404:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              description: |-
                The following error code:
                - notFound: A current representation for the target resource not found
              enum:
                - notFound
              type: string
          required:
            - code
          type: object
      description:
        Resource for the requested path not found.
        (https://tools.ietf.org/html/rfc7231#section-6.5.4)
    Error422:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              $ref: '#/components/schemas/Error422Code'
            propertyPath:
              description: |-
                A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used.
                Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901).
              type: string
          required:
            - code
          type: object
      description:
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
    Error422Code:
      description: |-
        One of the following error codes:
        - missingProperty: The property that was expected is not present in the payload
        - invalidValue: The property has an incorrect value
        - invalidFormat: The property value does not comply with the expected value format
        - referenceNotFound: The object referenced by the property cannot be identified in the target system
        - unexpectedProperty: Additional, not expected property has been provided
        - tooLargeDataset: A requested entity will produce too much data
        - tooManyRecords: The number of records to be provided in the response exceeds the  threshold
        - tooManyRequests: The number of simultaneous requests from one API client exceeds the threshold
        - otherIssue: Other problem was identified (detailed information provided in a reason)
      enum:
        - missingProperty
        - invalidValue
        - invalidFormat
        - referenceNotFound
        - unexpectedProperty
        - tooLargeDataset
        - tooManyRecords
        - tooManyRequests
        - otherIssue
      type: string
    Error500:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            code:
              description: |-
                The following error code:
                - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request.
              enum:
                - internalError
              type: string
          required:
            - code
          type: object
      description:
        Internal Server Error.
        (https://tools.ietf.org/html/rfc7231#section-6.6.1)
    Subscription:
      description:
        Provides stream metadata information that allows for data consumption.
      properties:
        id:
          description: A unique identifier for the stream.
          type: string
        description:
          description: An explanatory description of the stream.
          type: string
        priority:
          description: "The priority level of the stream. Can be high, medium,
            or\
            \ low."
          type: string
        connectionConfig:
          $ref: '#/components/schemas/ConnectionConfig'
      required:
        - id
      type: object
    Topic:
      additionalProperties: true
      description: |
        Provides metadata describing a topic available for subscription. This object is used to define available consumption mechanisms and the data model.
      properties:
        id:
          description: |
            An identifier for the topic. This can be used to uniquely identify the topic within the Server system.
          type: string
        category:
          $ref: '#/components/schemas/Category'
          description: |
            The category of the topic. This can be used to group topics based on their characteristics.
        modelRef:
          description: |
            A reference to a model that describes the structure of the data associated with the topic.
          format: uri
          type: string
        availableChannels:
          description: |
            An array of channel descriptions that provide information about the channels through which the topic can be accessed.
          items:
            $ref: '#/components/schemas/ChannelDescription'
          minItems: 1
          type: array
      required:
        - id
      type: object
    TopicSubscription:
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - $ref: '#/components/schemas/TopicSubscriptionRequest'
      description: Information about the subscription to a specific topic
    TopicSubscriptionRequest:
      additionalProperties: true
      properties:
        protocol:
          description: |
            Name of the protocol consumer is intended to use to consume data from `topicId`.  The name of the protocol must be one of the defined for the topic.
          type: string
        topicId:
          description: Identifier of the topic consumer wants to subscribe to
          type: string
      required:
        - protocol
        - topicId
      type: object
    ConnectionConfig:
      description:
        Configuration settings for establishing a connection to the stream.
      properties:
        servers:
          $ref: '#/components/schemas/servers'
        channel:
          $ref: '#/components/schemas/Channel'
      type: object
    servers:
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/Reference'
          - $ref: '#/components/schemas/server'
      description: The Servers Object is a map of Server Objects.
      type: object
    Channel:
      properties:
        name:
          description:
            The name of the channel through which the stream data is
            transmitted.
          format: uri-template
          minLength: 1
          type: string
        bindings:
          $ref: '#/components/schemas/bindingsObject'
      type: object
    bindingsObject:
      additionalProperties: true
      description: Map describing protocol-specific definitions for a server.
      properties:
        http:
          type: object
        ws:
          type: object
        amqp:
          type: object
        amqp1:
          type: object
        mqtt:
          type: object
        mqtt5:
          type: object
        kafka:
          type: object
        anypointmq:
          type: object
        nats:
          type: object
        jms:
          type: object
        sns:
          type: object
        sqs:
          type: object
        stomp:
          type: object
        redis:
          type: object
        ibmmq:
          type: object
        solace:
          type: object
        googlepubsub:
          type: object
        pulsar:
          type: object
      type: object
    SubscriptionRequest:
      additionalProperties: true
      properties:
        protocol:
          description: |
            Name of the protocol consumer is intended to use to consume data from `topicId`.  The name of the protocol must be one of the defined for the topic.
          type: string
        topicId:
          description: Identifier of the topic consumer wants to subscribe to
          type: string
      required:
        - protocol
        - topicId
      type: object
    ChannelDescription:
      properties:
        protocol:
          description: Name of technical protocol allowing for consumption
          type: string
        description:
          description: Human-friendly description of the protocol
          type: string
      required:
        - protocol
      type: object
    Reference:
      properties:
        $ref:
          $ref: '#/components/schemas/ReferenceObject'
      required:
        - $ref
      type: object
    ReferenceObject:
      description: "A simple object to allow referencing other components in
        the specification,\
        \ internally and externally."
      format: uri-reference
      type: string
    server:
      additionalProperties: false
      description: "An object representing a message broker, a server or any
        other\
        \ kind of computer program capable of sending and/or receiving data"
      properties:
        url:
          description: "A URL to the target host. This URL supports Server
            Variables\
            \ and MAY be relative, to indicate that the host location is
            relative\
            \ to the location where the AsyncAPI document is being served."
          type: string
        description:
          description:
            An optional string describing the host designated by the URL.
            CommonMark syntax MAY be used for rich text representation.
          type: string
        protocol:
          description: "The protocol this URL supports for connection.
            Supported protocol\
            \ include, but are not limited to: amqp, amqps, http, https, ibmmq,
            jms,\
            \ kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace,
            stomp, stomps,\
            \ ws, wss, mercure, googlepubsub."
          type: string
        protocolVersion:
          description: "The version of the protocol used for connection. For
            instance:\
            \ AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc."
          type: string
        variables:
          $ref: '#/components/schemas/serverVariables'
        security:
          description:
            'A declaration of which security mechanisms can be used with this
            server. The list of values includes alternative security
            requirement objects that can be used. '
          items:
            $ref: '#/components/schemas/SecurityRequirement'
          type: array
        bindings:
          $ref: '#/components/schemas/bindingsObject'
        tags:
          description:
            A list of tags for logical grouping and categorization of servers.
          items:
            $ref: '#/components/schemas/tag'
          type: array
          uniqueItems: true
      required:
        - protocol
        - url
      type: object
    serverVariables:
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/Reference'
          - $ref: '#/components/schemas/serverVariable'
      description:
        A map between a variable name and its value. The value is used for
        substitution in the server's URL template.
      type: object
    SecurityRequirement:
      additionalProperties:
        items:
          type: string
        type: array
        uniqueItems: true
      description:
        Lists of the required security schemes that can be used to execute an
        operation
      type: object
    tag:
      additionalProperties: false
      description: Allows adding meta data to a single tag.
      properties:
        name:
          description: The name of the tag.
          type: string
        description:
          description: A short description for the tag.
          type: string
        externalDocs:
          $ref: '#/components/schemas/externalDocs'
      required:
        - name
      type: object
    externalDocs:
      additionalProperties: false
      description:
        Allows referencing an external resource for extended documentation.
      properties:
        description:
          description: A short description of the target documentation.
          type: string
        url:
          description:
            The URL for the target documentation. This MUST be in the form of
            an absolute URL.
          format: uri
          type: string
      required:
        - url
      type: object
    serverVariable:
      additionalProperties: false
      description:
        An object representing a Server Variable for server URL template
        substitution.
      properties:
        enum:
          description:
            An enumeration of string values to be used if the substitution
            options are from a limited set.
          items:
            type: string
          type: array
          uniqueItems: true
        default:
          description: "The default value to use for substitution, and to send,
            if\
            \ an alternate value is not supplied."
          type: string
        description:
          description: 'An optional description for the server variable. '
          type: string
        examples:
          description: An array of examples of the server variable.
          items:
            type: string
          type: array
      type: object
    Category:
      description: |
        The category of the topic. This can be used to group topics based on their characteristics.
      enum:
        - Layer 1
        - Ethernet
        - IP
        - SD-WAN
        - Computing
        - Storage
        - Memory
      type: string