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:
  - name: topic
    description: Groups all operations related to the available topic.
  - name: subscription
    description: >+
      Groups all operations related to subscribed topics and 
      subscription management.
  - name: events subscription
paths:
  /topic:
    get:
      operationId: topicList
      summary: Retrieve Available Topics
      description: List topics available for subscription to performance monitoring data
      parameters:
        - name: category
          required: false
          in: query
          description: Category of the available topic
          schema:
            type: string
        - name: protocol
          required: false
          in: query
          description: A communication protocol supported by the available topic
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      tags:
        - topic
      responses:
        '200':
          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
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Topic'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'
  /topic/{id}:
    get:
      operationId: topicById
      summary: Retrieve Available Topic by an Identifier
      description: Information about the topic available for subscription
      tags:
        - topic
      parameters:
        - name: id
          description: Identifier of the topic
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Topic'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'
  /subscription:
    get:
      operationId: subscriptionList
      summary: Retrieve Topic Subscriptions List
      description: List all the subscriptions to all the topics
      tags:
        - subscription
      parameters:
        - name: topicId
          required: false
          in: query
          description: Identifier of a topic subscription belongs to
          schema:
            type: string
        - name: protocol
          required: false
          in: query
          description: A communication protocol supported by the available topic
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          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
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopicSubscription'
            'application/vnd.aai.asyncapi+json':
              schema:
                $ref: '#/components/schemas/AsyncAPIModel'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'
    post:
      operationId: subscribeTopic
      summary: Subscribe To a Topic
      description: Subscribe to the selected topic
      tags:
        - subscription
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/TopicSubscriptionRequest'
      responses:
        '201':
          description: Registered
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/TopicSubscription'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /subscription/{id}:
    delete:
      operationId: unsubscribeTopic
      summary: Unsubscribe From a Topic
      description: Remove a subscription for a  topic
      parameters:
        - name: id
          description: Identifier of the subscription
          required: true
          in: path
          schema:
            type: string
      tags:
        - subscription
      responses:
        '204':
          description: Unsubscribe operation successful 
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'
    get:
      operationId: subscriptionById
      summary: Retrieve Topic Subscription By an Identifier
      description: Retrieve information about a subscription to a topic
      tags:
        - subscription
      parameters:
        - name: id
          description: Identifier of the subscription
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/TopicSubscription'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'

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
      schema:
        format: int32
        type: integer
    Limit:
      description: >-
        Requested number of elements to be provided in response requested by
        client
      in: query
      name: limit
      schema:
        format: int32
        type: integer
  schemas:
    AsyncAPIModel:
      $ref: 'http://asyncapi.com/definitions/2.6.0/asyncapi.json'
    Error:
      type: object
      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:
          type: string
          description: >-
            Text that provides mode details and corrective actions related to
            the error. This can be shown to a client user.
        reason:
          type: string
          description: >-
            Text that explains the reason for the error. This can be shown to a
            client user.
          maxLength: 255
        referenceError:
          type: string
          description: URL pointing to documentation describing the error
          format: uri
      required:
        - reason
    Error400:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              $ref: '#/components/schemas/Error400Code'
          required:
            - code
      description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
    Error400Code:
      type: string
      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
    Error401:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              $ref: '#/components/schemas/Error401Code'
          required:
            - code
      description: 'Unauthorized.  (https://tools.ietf.org/html/rfc7235#section-3.1)'
    Error401Code:
      type: string
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      enum:
        - missingCredentials
        - invalidCredentials
    Error403:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              $ref: '#/components/schemas/Error403Code'
          required:
            - code
      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:
      type: string
      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
    Error404:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              type: string
              description: |-
                The following error code:
                - notFound: A current representation for the target resource not found
              enum:
                - notFound
          required:
            - code
      description: >-
        Resource for the requested path not found.
        (https://tools.ietf.org/html/rfc7231#section-6.5.4)
    Error422:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              $ref: '#/components/schemas/Error422Code'
            propertyPath:
              type: string
              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).
          required:
            - code
      description: >-
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
    Error422Code:
      type: string
      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
    Error500:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              type: string
              description: >-
                The following error code:

                - internalError: Internal server error - the server encountered
                an unexpected condition that prevented it from fulfilling the
                request.
              enum:
                - internalError
          required:
            - code
      description: >-
        Internal Server Error.
        (https://tools.ietf.org/html/rfc7231#section-6.6.1)

    Subscription:
      $ref: models/Subscription.yaml
    Topic:
      $ref: models/Topic.yaml
    TopicSubscription:
      description: Information about the subscription to a specific topic
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - $ref: '#/components/schemas/TopicSubscriptionRequest'
    TopicSubscriptionRequest:
      $ref: 'models/SubscriptionRequest.yaml'
  responses:
    '400':
      description: Bad Request
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error400'
    '401':
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error401'
      description: Unauthorized
    '403':
      description: Forbidden
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error403'
    '404':
      description: Not Found
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/Error404'
    '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