path: root/components/pm-subscription-handler/pmsh_service/mod/api/pmsh_swagger.yml

# ============LICENSE_START=======================================================
#  Copyright (C) 2020-2022 Nordix Foundation.
# ================================================================================
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0
# ============LICENSE_END=========================================================

swagger: "2.0"
info:
  title: PM Subscription Handler Service
  version: "2.0.0"
  description: PM subscription handler enables control of performance management jobs on network functions in ONAP
consumes:
  - "application/json"
produces:
  - "application/json"
basePath: "/"
schemes:
  - https
  - http
# Paths supported by the server application
paths:
  /healthcheck:
    get:
      operationId: mod.api.controller.status
      tags:
        - "HealthCheck"
      description: >-
        This is the health check endpoint. If this returns a 200, the server is alive.
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              status:
                type: string
                description: Overall health of PMSH
                enum: [healthy, unhealthy]
        503:
          description: the pmsh service is unavailable

  /subscription:
    post:
      tags:
        - "Subscription"
      description: >-
        Create a PM Subscription
      operationId: mod.api.controller.post_subscription
      parameters:
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/subscription"
      responses:
        201:
          description: successfully created PM Subscription
        409:
          description: Duplicate data
        400:
          description: Invalid input

    get:
      description: Get all the subscriptions from PMSH.
      operationId: mod.api.controller.get_subscriptions
      tags:
        - "Subscription"
      responses:
        200:
          description: OK; Array of subscriptions are returned else empty if not found
          schema:
            type: array
            items:
              $ref: "#/definitions/subscription"
        500:
          description: Exception occurred while querying database

  /subscription/{subscription_name}:
    get:
      description: Get the Subscription from PMSH specified by Name
      operationId: mod.api.controller.get_subscription_by_name
      tags:
        - "Subscription"
      parameters:
        - name: subscription_name
          in: path
          required: true
          description: Name of the subscription
          type: string
      responses:
        200:
          description: OK; Requested Subscription was returned
          schema:
            $ref : "#/definitions/subscription"
        404:
          description: Subscription with specified name not found
        500:
          description: Exception occurred while querying database

    delete:
      description: Deletes the Subscription from PMSH specified by Name
      operationId: mod.api.controller.delete_subscription_by_name
      tags:
        - "Subscription"
      parameters:
        - name: subscription_name
          in: path
          required: true
          description: The name of the subscription to delete
          type: string
      responses:
        204:
          description: Successfully deleted the subscription and returns NO Content
        404:
          description: Subscription with the specified name not found
        409:
          description: Subscription could not be deleted as it contains measurement groups
                       with state UNLOCKED OR state change to LOCKED was under process
        500:
          description: Exception occurred on the server

  /subscription/{subscription_name}/nfFilter:
    put:
      tags:
        - "Subscription"
      description: >-
        Update a Subscription nf filter
      operationId: mod.api.controller.put_nf_filter
      parameters:
        - name: subscription_name
          in: path
          required: true
          description: The name of the subscription to update nf filters
          type: string
        - in: "body"
          name: "body"
          required: true
          schema:
            $ref: "#/definitions/nfFilter"
      responses:
        201:
          description: Successfully updated nf filter
        409:
          description: Conflicting data
        400:
          description: Invalid input
        500:
          description: Exception occurred while querying database

  /subscription/{subscription_name}/measurementGroups/{measurement_group_name}:
    post:
      description: Create a measurement group for a given subscription
      operationId: mod.api.controller.post_meas_group
      tags:
        - "Measurement Group"
      parameters:
        - name : subscription_name
          in: path
          required: true
          description: Name of the subscription
          type: string
        - name: measurement_group_name
          in: path
          required: true
          description: Name of the measurement group
          type: string
        - name: "body"
          in: "body"
          required: true
          schema:
            $ref: "#/definitions/measurementGroup"
      responses:
        201:
          description: Successfully created measurement group
        404:
          description: Subscription with the specified name not found
        409:
          description: Duplicate data
        500:
          description: Internal server error

    get:
      description: Get the  measurement group and associated network functions
                  from PMSH by using sub name and meas group name
      operationId: mod.api.controller.get_meas_group_with_nfs
      tags:
        - "Measurement Group"
      parameters:
        - name : subscription_name
          in: path
          required: true
          description: Name of the subscription
          type: string
        - name: measurement_group_name
          in: path
          required: true
          description: Name of the measurement group name
          type: string
      responses:
        200:
          description: OK; Received requested measurement group with associated NF's
          schema:
            $ref : "#/definitions/measGroupWithNFs"
        404:
          description: Measurement group with specified name not found
        500:
          description: Exception occurred while querying database

    delete:
      description: Delete a measurement group
      operationId: mod.api.controller.delete_meas_group_by_name
      tags:
        - "Measurement Group"
      parameters:
        - name : subscription_name
          in: path
          required: true
          description: Name of the subscription
          type: string
        - name: measurement_group_name
          in: path
          required: true
          description: Name of the measurement group name
          type: string
      responses:
        204:
          description: Successfully deleted the measurement group and returns NO Content
        404:
          description: Measurement group with the specified name not found
        409:
          description: Measurement group not deleted because state UNLOCKED OR state change to LOCKED was under process
        500:
          description: Exception occurred on the server

  /subscription/{subscription_name}/measurementGroups/{measurement_group_name}/adminState:
    put:
      description: Update the admin status of the Measurement Group by using sub name and measurement group name
      operationId: mod.api.controller.update_admin_state
      tags:
        - "Measurement Group"
      parameters:
        - name: subscription_name
          in: path
          required: true
          description: Name of the subscription
          type: string
        - name: measurement_group_name
          in: path
          required: true
          description: Name of the measurement group
          type: string
        - in: "body"
          name: "body"
          required: true
          schema:
            properties:
              administrativeState:
                type: string
                enum: [ LOCKED, UNLOCKED ]
      responses:
        200:
          description: Successfully updated admin state
        409:
          description: Cannot update as Locked request is in progress
        400:
          description: Invalid input request details
        500:
          description: Exception details of server failure

definitions:
  subscription:
    type: object
    properties:
      subscription:
        type: object
        properties:
          subscriptionName:
            type: string
          operationalPolicyName:
            type: string
          controlLoopName:
            type: string
          nfFilter:
            $ref: "#/definitions/nfFilter"
          measurementGroups:
            type: array
            minItems: 1
            items:
              $ref: "#/definitions/measurementGroup"
        required:
          - subscriptionName
          - operationalPolicyName
          - nfFilter
          - measurementGroups
    required:
      - subscription

  nfFilter:
    type: object
    description: "At least one valid filter value within nfFilter is required"
    additionalProperties: false
    properties:
      nfNames:
        type: array
        items:
          type: string
      modelInvariantIDs:
        type: array
        items:
          type: string
      modelVersionIDs:
        type: array
        items:
          type: string
      modelNames:
        type: array
        items:
          type: string
    required:
      - nfNames
      - modelInvariantIDs
      - modelVersionIDs
      - modelNames

  measurementGroup:
    type: object
    properties:
      measurementGroup:
        type: object
        properties:
          measurementGroupName:
            type: string
          fileBasedGP:
            type: integer
          fileLocation:
            type: string
          administrativeState:
            type: string
            enum: [LOCKED, UNLOCKED]
          measurementTypes:
            type: array
            minItems: 1
            items:
              $ref: "#/definitions/measurementType"
          managedObjectDNsBasic:
            type: array
            minItems: 1
            items:
              $ref: "#/definitions/managedObjectDNs"
        allOf:
          - required:
              - measurementGroupName
              - fileBasedGP
              - fileLocation
              - administrativeState
              - measurementTypes
              - managedObjectDNsBasic
    required:
      - measurementGroup

  measurementType:
    type: object
    properties:
      measurementType:
        type: string
    required:
      - measurementType

  managedObjectDNs:
    type: object
    properties:
      DN:
        type: string
    required:
      - DN

  measGroupWithNFs:
    type: object
    properties:
      subscriptionName:
        type: string
      measurementGroupName:
        type: string
      administrativeState:
        type: string
        enum: [ LOCKED, UNLOCKED ]
      fileBasedGP:
        type: integer
      fileLocation:
        type: string
      measurementTypes:
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/measurementType"
      managedObjectDNsBasic:
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/managedObjectDNs"
      network_functions:
        type: array
        items:
          type: object
          properties:
            nfName:
              type: string
              description: Name of the Network Function
            ipv4Address:
              type: string
              description: Address of the IPV4
            ipv6Address:
              type: string
              description: Address of the IPV6
            nfMgStatus:
              type: string
              description: status of network function for one meas group
            modelInvariantId:
              type: string
              description: ID of the model invariant
            modelVersionId:
              type: string
              description: ID of the model version
            modelName:
              type: string
              description: Name of the model
            sdncModelName:
              type: string
              description: Name of the sdnc model
            sdncModelVersion:
              type: string
              description: Version of the sdnc model