#  ============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: Operation permission API
  description: "Allows a client application to execute a permission request defined by a third party implementation before proceeding with an operation. As an example, a permission can be requested before performing any configuration management operation."
  version: 1.0.0-alpha.1+1
  contact:
    name: CPS team
    url: https://lf-onap.atlassian.net/wiki/spaces/DW/pages/16442177/Configuration+Persistence+Service+Developer+s+Landing+Page
    email: cpsteam@est.tech
  license:
    name: Copyright (C) 2024 Nordix Foundation
  x-audience: external-partner
  x-api-id: c7fc2f5b-16bd-4bcb-8ac8-ea8d543fcc15
tags:
  - name: Operation permission
    description: "Initiate a permission request on an operation."
servers:
  - url: http://{hostname}/operation-permission/v1
security:
  - bearerAuth: []
paths:
  /permissions:
    post:
      description: "Initiate permission request"
      operationId: initiatePermissionRequest
      parameters:
        - name: Content-Type
          description: This specifies the media type of the request sent by the client to the server
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Accept
          description: Indicates the response media type accepted by the client.
          in: header
          required: false
          schema:
            type: string
            default: application/json
        - description: Bearer token may be used to identify client as part of a policy
          explode: false
          in: header
          name: Authorization
          required: false
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionRequest'
        description: "The permission request body"
        required: true
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
        - Operation permission
components:
  securitySchemes:
    bearerAuth:
      type: http
      description: "Bearer token (from a client),used by policies to identify the client"
      scheme: bearer
  schemas:
    ErrorMessage:
      type: object
      title: Error
      properties:
        status:
          type: string
        title:
          type: string
        details:
          type: string
    Operation:
      example:
        operation: update
        entityHandleId: ABCD123450d7A822AB27B386829FD9E12
        resourceIdentifier: ManagedElement=Kista/GNBDUFunction=1/UECC=1
        targetIdentifier: MEContext=RadioNode-K6_0001,ManagedElement=RadioNode-K6_0001
        changeRequest:
          Cell:
            - id: Cell-id
              attributes:
              administrativeState: UNLOCKED
      properties:
        operation:
          description: Currently supported operations are 'create', 'update', 'patch', 'delete'. For other possible operation types see the client documentation.
          example: update
          type: string
        entityHandleId:
          description: A unique identifier for the network element.
          example: ABCD123450d7A822AB27B386829FD9E12
          type: string
        resourceIdentifier:
          description: Identifies the object in the node model. Currently supported separators are '/' and ','. For other possible format see the client documentation.
          example: ManagedElement=Kista/GNBDUFunction=1/UECC=1
          type: string
        targetIdentifier:
          description: FDN of the target node. Currently supported separators are '/' and ','. For other possible format see the client documentation.
          example: MEContext=RadioNode-K6_0001/ManagedElement=RadioNode-K6_0001
          type: string
        changeRequest:
          description: All the information that is required to identify which parameters and attributes of the network is changing.
          example:
            Cell:
              - id: Cell-id
                attributes:
                  administrativeState: UNLOCKED
          type: object
      required:
        - operation
        - targetIdentifier
      type: object
    PermissionRequest:
      example:
        permissionId: 550e8400-e29b-41d4-a716-446655440000
        changeRequestFormat: cm-legacy
        operations:
          - operation: update
            entityHandleId: ABCD123450d7A822AB27B386829FD9E12
            resourceIdentifier: ManagedElement=Kista/GNBDUFunction=1/UECC=1
            targetIdentifier: MEContext=RadioNode-K6_0001/ManagedElement=RadioNode-K6_0001
            changeRequest:
              Cell:
                - id: Cell-id
                  attributes:
                    administrativeState: UNLOCKED
          - operation: delete
            entityHandleId: DCBA123450d7A822AB27B386829FD9E12
            resourceIdentifier: ManagedElement=Kista/GNBDUFunction=1/UECC=1
            targetIdentifier: MEContext=RadioNode-K6_0002/ManagedElement=RadioNode-K6_0002
      properties:
        permissionId:
          description: Unique ID for the permission request (for auditing purposes)
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        changeRequestFormat:
          description: Format of the change request. Currently supported 'cm-legacy'. For other possible formats see the client documentation.
          example: cm-legacy
          type: string
        operations:
          items:
              $ref: '#/components/schemas/Operation'
          type: array
      required:
        - operations
        - changeRequestFormat
      type: object
    PermissionResponse:
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        permissionResult: deny
        message: Object locked due to recent changes
      properties:
        id:
          description: Unique ID for the permission request (for auditing purposes)
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        permissionResult:
          description: "The decision outcome. Currently supported values: 'allow','deny'"
          example: deny
          type: string
        message:
          description: Additional information regarding the decision outcome
          example: Object locked due to recent change
          type: string
      required:
        - id
        - permissionResult
        - message
      type: object

  responses:
    BadRequest:
      description: "Bad Request"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: '400'
            title: "Bad Request"
            details: "The provided request is not valid"
    Unauthorized:
      description: "Unauthorized request"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: '401'
            title: "Unauthorized request"
            details: "This request is unauthorized"
    Forbidden:
      description: "Forbidden"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: '403'
            title: "Request Forbidden"
            details: "This request is forbidden"

    InternalServerError:
      description: "Internal Server Error"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          example:
            status: '500'
            title: "Internal Server Error"
            details: "Internal server error occurred"