openapi/openapi-datajob.yml

#  ============LICENSE_START=======================================================
#  Copyright (C) 2024 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=========================================================

openapi: 3.0.3
info:
  title: NCMP Data Subjob API
  description: Support datajobs through one or more subjob for each DMI and Data Producer Identifier combination
  version: 1.0.0
servers:
  - url: /dmi
tags:
  - description: DMI plugin rest apis
    name: dmi-datajob
paths:
  /v1/dataJob/{requestId}:
    post:
      description: Create a read request
      operationId: createReadRequest
      parameters:
        - $ref: '#/components/parameters/requestIdInPath'
      requestBody:
        description: Operation body
        content:
          application/3gpp-json-patch+json:
            schema:
              $ref: '#/components/schemas/SubjobRequest'
      tags:
        - dmi-datajob
      responses:
        "200":
          description: Response for subjob
          content:
            application/json:
              schema:
                type: object
                properties:
                  dataProducerJobId:
                    type: string
                    description: The data job ID.
components:
  parameters:
    requestIdInPath:
      description: Identifier for the overall Datajob
      in: path
      name: requestId
      required: true
      schema:
        example: some-identifier
        type: string
  schemas:
    SubjobRequest:
      type: object
      required:
        - dataProducerId
        - data
      properties:
        dataAcceptType:
          description: Defines the data response accept type
          example: application/vnd.3gpp.object-tree-hierarchical+json
          type: string
        dataContentType:
          description: Defines the data request content type
          example: application/3gpp-json-patch+json
          type: string
        dataProducerId:
          description: ID of the producer registered by DMI for the paths in the operations in this request
          example: my-data-producer-identifier
          type: string
        data:
          oneOf:
            - $ref: '#/components/schemas/ReadOperation'
            - $ref: '#/components/schemas/WriteOperation'
    ReadOperation:
      example:
        op: read
        operationId: 1
        path: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003/GNBCUCPFunction=2
        attributes: userLabel
        scope:
          scopeTyp: BASE_ONLY
      type: array
      items:
        type: object
        required:
          - path
          - op
        properties:
          path:
            description: Defines the resource on which operation is executed
            example: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003
            type: string
          op:
            description: Describes the operation to execute
            example: read
            type: string
          operationId:
            description: Unique identifier for the operation within the request
            example: 1
            type: string
          attributes:
            description: This parameter specifies the attributes of the scoped resources that are returned
            type: array
            items:
              example: cellId
              type: string
          fields:
            description: This parameter specifies the attribute fields of the scoped resources that are returned
            type: array
            items:
              type: string
          filter:
            description: This parameter is used to filter the scoped Managed Objects. Only Managed Objects passing the filter criteria will be fetched
            example: NRCellDU/attributes/administrativeState==LOCKED
            type: string
          scopeType:
            description: ScopeType selects MOs depending on relationships with Base Managed Object
            example: BASE_ONLY
            type: string
          scopeLevel:
            description: Only used when the scope type is BASE_NTH_LEVEL to specify amount of levels to search
            example: 0
            type: integer
          moduleSetTag:
            description: Module set identifier
            example: my-module-set-tag
            type: string
          cmHandleProperties:
            description: Private properties of the cm handle for the given path
            $ref: '#/components/schemas/CmHandleProperties'
    WriteOperation:
      example:
        op: add
        path: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003/GNBCUCPFunction=1/EUtraNetwork=1/EUtranFrequency=12
        value:
          id: 12
          attributes:
            userLabel: label12
      type: array
      items:
        type: object
        required:
          - path
          - op
        properties:
          path:
            description: Defines the resource on which operation is executed
            example: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003
            type: string
          op:
            description: Describes the operation to execute
            example: add
            type: string
          operationId:
            description: Unique identifier for the operation within the request
            example: 1
            type: string
          value:
            description: Value dependent on the op specified. Resource for an add. Object for a replace. ActionParameters for an action.
            type: object
            oneOf:
              - $ref: '#/components/schemas/Resource'
              - $ref: '#/components/schemas/ActionParameters'
              - $ref: '#/components/schemas/Object'
    CmHandleProperties:
      description: Private properties of the cm handle for the given path
      type: object
    Resource:
      type: object
      properties:
        id:
          description: Identifier of the resource object
          example: resource-identifier
          type: string
        attributes:
          description: Key value map representing the objects class attributes and values
          type: object
          additionalProperties:
            example: 'userLabel: label11'
            type: string
    ActionParameters:
      description: The input of the action in the form of key value pairs
      type: object
      additionalProperties:
        type: string
    Object:
      type: object