Improve PMS API with Best Practice Suggestions

Issue-ID: CCSDK-3985
Signed-off-by: Raviteja Karumuri <raviteja.karumuri@est.tech>
Change-Id: Ic1983d1c61a3837902d1012844e86f3c2365d4d1

1 files changed, 172 insertions, 175 deletions

diff --git a/a1-policy-management/api/pms-api.yaml b/a1-policy-management/api/pms-api.yaml
index c6ab05a8..699d5edc 100644
--- a/a1-policy-management/api/pms-api.yaml
+++ b/a1-policy-management/api/pms-api.yaml
@@ -1,6 +1,6 @@
 #  ============LICENSE_START=======================================================
 #  Copyright (C) 2020-2023 Nordix Foundation
-#  Copyright (C) 2023 OpenInfra Foundation Europe. All rights reserved.
+#  Copyright (C) 2023-2024 OpenInfra Foundation Europe. All rights reserved.
 #  Modifications Copyright (C) 2021 Pantheon.tech
 #  Modifications Copyright (C) 2021 Bell Canada
 #  ================================================================================
@@ -21,8 +21,10 @@
 
 openapi: 3.0.3
 info:
+  x-api-id: a31c510b-20e6-4a08-af16-368c44d7fba8
+  x-audience: external-public
   description: "<h2>General</h2><p>The O-RAN Non-RT RIC Policy Management Service\
-    \ provides a REST API for management of A1 policies. <br/>The main tasks of the\
+    \ provides a REST API for managemecnt of A1 policies. <br/>The main tasks of the\
     \ service are:</p><ul><li>A1 Policy creation, modification and deletion.</li><li>Monitoring\
     \ and maintaining consistency of the SMO view of A1 policies and the Near-RT RICs</li><li>Maintaining\
     \ a view of supported Near-RT RIC policy types</li><li>Supervision of using services\
@@ -51,19 +53,34 @@ info:
     name: Copyright (C) 2020-2023 Nordix Foundation. Licensed under the Apache License.
     url: http://www.apache.org/licenses/LICENSE-2.0
   title: A1 Policy Management Service
-  version: 1.2.0
+  version: 1.3.0
+  contact:
+    url: https://www.onap.org/
+    email: discuss-list@onap.com
 servers:
   - url: /
 tags:
-  - description: "API used for authorization of information A1 policy access (this is 
+  - name: A1 Policy Management
+    description: "API used to create polices, Policy Instances and get them as individual
+    using an ID or get all policies/Instances."
+  - name: NearRT-RIC Repository
+    description: "API used to get the NearRT-RIC for the managed element."
+  - name: Service Registry and Supervision
+    description: "API used to keep the service Alive with in the timeout period"
+  - name: Health Check
+    description: "API used to get the health status and statistics of this service"
+  - name: Service callbacks
+  - name: Authorization API
+    description: "API used for authorization of information A1 policy access (this is
      provided by an authorization producer such as OPA). <br> Note that this API is called
      by PMS, it is not provided."
-    name: Authorization API
-  - description: Monitor and interact
+  - name: Configuration
+    description: "API used to create or fetch the application configuration."
+  - name: Actuator
+    description: Monitor and interact
     externalDocs:
       description: Spring Boot Actuator Web API Documentation
       url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/
-    name: Actuator
 paths:
   /a1-policy/v2/policy-instances:
     get:
@@ -114,13 +131,13 @@ paths:
                   $ref: '#/components/examples/policy_info_list'
               schema:
                 $ref: '#/components/schemas/policy_info_list'
-          description: Policies
+          description: OK - Returns A1 Policies which matches the criteria
         "404":
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/error_information'
-          description: "Near-RT RIC, policy type or service not found"
+          description: "Not Found - Near-RT RIC, policy type or service not found"
       summary: Query for A1 policy instances
       tags:
         - A1 Policy Management
@@ -141,11 +158,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/authorization_result'
           description: OK
+        "403":
+          $ref: '#/components/responses/Forbidden'
       summary: Request for access authorization.
       tags:
         - Authorization API
   /actuator/threaddump:
     get:
+      x-internal: true
       operationId: threaddump
       responses:
         "200":
@@ -178,12 +198,13 @@ paths:
               examples:
                 status_info:
                   $ref: '#/components/examples/status_info'
-          description: Service is living
-      summary: Returns status and statistics of this service
+          description: OK- Service is living Ok
+      description: Returns status and statistics of this service
       tags:
         - Health Check
   /actuator/loggers:
     get:
+      x-internal: true
       operationId: loggers
       responses:
         "200":
@@ -203,6 +224,7 @@ paths:
         - Actuator
   /actuator/health/**:
     get:
+      x-internal: true
       operationId: health-path
       responses:
         "200":
@@ -253,18 +275,16 @@ paths:
               examples:
                 ric_info:
                   $ref: '#/components/examples/ric_info'
-          description: Near-RT RIC is found
+          description: OK - Near-RT RIC is found
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC is not found
-      summary: Returns info for one Near-RT RIC
+          $ref: '#/components/responses/NotFound'
+          description: NotFound - Requested NearRT-RIC Not Found
+      summary: Returns info of Near-RT RIC queried by the ric-id and managed-element-id
       tags:
         - NearRT-RIC Repository
   /actuator/shutdown:
     post:
+      x-internal: true
       operationId: shutdown
       responses:
         "200":
@@ -323,18 +343,16 @@ paths:
                   $ref: '#/components/examples/policy_type_id_list'
               schema:
                 $ref: '#/components/schemas/policy_type_id_list'
-          description: Policy type IDs
+          description: OK - Policy Type IDs Found
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC is not found
-      summary: Query policy type identities
+          $ref: '#/components/responses/NotFound'
+          description: 'Not Found - Requested Policy Type IDs Not Found'
+      description: Query policy type identities
       tags:
         - A1 Policy Management
   /a1-policy/v2/policies/{policy_id}:
     delete:
+      description: Deleting the policy using the Policy's Policy ID.
       operationId: deletePolicy
       parameters:
         - explode: false
@@ -350,25 +368,10 @@ paths:
             '*/*':
               schema:
                 $ref: '#/components/schemas/void'
-          description: Not used
+          description: OK - Policy deleted
         "423":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC is not operational
-        "204":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/void'
-          description: Policy deleted
-        "404":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Policy is not found
+          $ref: '#/components/responses/Locked'
+          description: 'The requested policy using policy_id is Locked'
       summary: Delete a policy
       tags:
         - A1 Policy Management
@@ -391,18 +394,16 @@ paths:
               examples:
                 policy_info:
                   $ref: '#/components/examples/policy_info'
-          description: Policy found
+          description: OK - Policy found
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Policy is not found
-      summary: Returns a policy
+          $ref: '#/components/responses/NotFound'
+          description: 'Not Found - Requested Policy using policy_id is not found'
+      description: Returns a policy
       tags:
         - A1 Policy Management
   /actuator/metrics/{requiredMetricName}:
     get:
+      x-internal: true
       operationId: metrics-requiredMetricName
       parameters:
         - explode: false
@@ -430,6 +431,7 @@ paths:
         - Actuator
   /a1-policy/v2/configuration:
     get:
+      x-internal: true
       operationId: getConfiguration
       responses:
         "200":
@@ -437,17 +439,15 @@ paths:
             application/json:
               schema:
                 type: string
-          description: Configuration
+          description: OK - Configuration
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: File is not found or readable
-      summary: Returns the contents of the application configuration file
+          $ref: '#/components/responses/NotFound'
+          description: Not Found - Configuration is not found or readable
+      description: Returns the contents of the application configuration file
       tags:
-        - configuration
+        - Configuration
     put:
+      x-internal: true
       operationId: putConfiguration
       requestBody:
         content:
@@ -461,25 +461,15 @@ paths:
             '*/*':
               schema:
                 $ref: '#/components/schemas/void'
-          description: Configuration updated
+          description: OK - Configuration updated
         "400":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Invalid configuration provided
-        "500":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Something went wrong when replacing the configuration. Try
-            again.
-      summary: Replace the current configuration file with the given configuration
+          $ref: '#/components/responses/BadRequest'
+      description: Replace the current configuration with the given configuration
       tags:
-        - configuration
+        - Configuration
   /actuator:
     get:
+      x-internal: true
       operationId: links
       responses:
         "200":
@@ -511,6 +501,7 @@ paths:
         - Actuator
   /actuator/loggers/{name}:
     get:
+      x-internal: true
       operationId: loggers-name
       parameters:
         - explode: false
@@ -537,6 +528,7 @@ paths:
       tags:
         - Actuator
     post:
+      x-internal: true
       operationId: loggers-name_2
       parameters:
         - explode: false
@@ -591,18 +583,15 @@ paths:
             '*/*':
               schema:
                 type: object
-          description: "Service supervision timer refreshed, OK"
+          description: "OK - Service supervision timer refreshed, OK"
         "404":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: "The service is not found, needs re-registration"
+          $ref: '#/components/responses/NotFound'
       summary: Heartbeat indicates that the service is running
       tags:
         - Service Registry and Supervision
   /actuator/metrics:
     get:
+      x-internal: true
       operationId: metrics
       responses:
         "200":
@@ -646,11 +635,7 @@ paths:
                   $ref: '#/components/examples/ric_info_list'
           description: OK
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Policy type is not found
+          $ref: '#/components/responses/NotFound'
       summary: Query Near-RT RIC information
       tags:
         - NearRT-RIC Repository
@@ -679,11 +664,7 @@ paths:
                   $ref: '#/components/examples/service_status_list'
           description: OK
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Service is not found
+          $ref: '#/components/responses/NotFound'
       summary: Returns service information
       tags:
         - Service Registry and Supervision
@@ -706,46 +687,45 @@ paths:
             '*/*':
               schema:
                 type: object
-          description: Service updated
+          description: OK - Service updated
         "201":
           content:
             '*/*':
               schema:
                 type: object
-          description: Service created
+          description: Created - Service created
         "400":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: The ServiceRegistrationInfo is not accepted
+          $ref: '#/components/responses/BadRequest'
       summary: Register a service
       tags:
         - Service Registry and Supervision
       callbacks:
         RICStatus:
           "{$request.body#/callback_url}":
-           post:
-            description: The URL to this call is registered at Service registration.
-            operationId: serviceCallback
-            requestBody:
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/service_callback_info_v2'
-              required: true
-            responses:
-              "200":
+            post:
+              description: The URL to this call is registered at Service registration.
+              operationId: serviceCallback
+              requestBody:
                 content:
                   application/json:
                     schema:
-                      $ref: '#/components/schemas/void'
-                description: OK
-            summary: Callback for Near-RT RIC status
-            tags:
-              - Service callbacks
+                      $ref: '#/components/schemas/service_callback_info_v2'
+                required: true
+              responses:
+                "200":
+                  content:
+                    application/json:
+                      schema:
+                        $ref: '#/components/schemas/void'
+                  description: OK
+                "404":
+                  $ref: '#/components/responses/NotFound'
+              summary: Callback for Near-RT RIC status
+              tags:
+                - Service callbacks
   /actuator/info:
     get:
+      x-internal: true
       operationId: info
       responses:
         "200":
@@ -772,8 +752,8 @@ paths:
             '*/*':
               schema:
                 type: string
-          description: Service is living
-      summary: Returns status and statistics of this service
+          description: OK -  Service is living
+      description: Returns status and statistics of this service
       tags:
         - Health Check
   /a1-policy/v2/policy-types/{policytype_id}:
@@ -796,18 +776,15 @@ paths:
               examples:
                 policy_type_definition:
                   $ref: '#/components/examples/policy_type_definition'
-          description: schema of the given policy type
+          description: OK - schema of the given policy type
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Policy type is not found
-      summary: Returns a policy type definition
+          $ref: '#/components/responses/NotFound'
+      description: Returns a policy type definition
       tags:
         - A1 Policy Management
   /actuator/logfile:
     get:
+      x-internal: true
       operationId: logfile
       responses:
         "200":
@@ -821,6 +798,7 @@ paths:
         - Actuator
   /actuator/health:
     get:
+      x-internal: true
       operationId: health
       responses:
         "200":
@@ -887,13 +865,9 @@ paths:
                   $ref: '#/components/examples/policy_id_list'
               schema:
                 $ref: '#/components/schemas/policy_id_list'
-          description: Policy identities
+          description: OK - Policy identities
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC or type not found
+          $ref: '#/components/responses/NotFound'
       summary: Query policy identities
       tags:
         - A1 Policy Management
@@ -911,26 +885,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/void'
-          description: Policy updated
+          description: OK - Policy updated
         "201":
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/void'
-          description: Policy created
+          description: Created - Policy created
         "423":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC is not operational
-        "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Near-RT RIC or policy type is not found
-      summary: Create or update a policy
+          $ref: '#/components/responses/Locked'
+      description: Create or update a policy
       tags:
         - A1 Policy Management
   /a1-policy/v2/services/{service_id}:
@@ -945,29 +909,20 @@ paths:
             type: string
           style: simple
       responses:
-        "200":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/void'
-          description: Not used
         "204":
           content:
             '*/*':
               schema:
                 type: object
-          description: Service unregistered
+          description: No Content - Service unregistered
         "404":
-          content:
-            '*/*':
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Service not found
-      summary: Unregister a service
+          $ref: '#/components/responses/NotFound'
+      description: Unregister a service
       tags:
         - Service Registry and Supervision
   /actuator/heapdump:
     get:
+      x-internal: true
       operationId: heapdump
       responses:
         "200":
@@ -994,22 +949,56 @@ paths:
         "200":
           content:
             application/json:
+              schema:
+                $ref: '#/components/schemas/policy_status_info'
               examples:
                 policy_status_info:
                   $ref: '#/components/examples/policy_status_info'
-              schema:
-                $ref: '#/components/schemas/policy_status_info'
-          description: Policy status
+          description: OK -  Policy status
         "404":
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/error_information'
-          description: Policy is not found
-      summary: Returns a policy status
+          $ref: '#/components/responses/NotFound'
+      description: Returns a policy status
       tags:
         - A1 Policy Management
 components:
+  responses:
+    Locked:
+      description: "Locked - HTTP Status code which can be used when the state is Locked"
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/error_information'
+          example:
+            status: 423
+            title: Locked
+            detail: Requested resource is in a locked state.
+    BadRequest:
+      description: Bad Request
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/error_information'
+          example:
+            status: 400
+            title: Bad Request
+            detail: The provided request is not valid.
+    Forbidden:
+      description: Forbidden
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/error_information'
+          example:
+            status: 403
+            title: Forbidden
+            detail: Your role does not allow to perform this action. Contact System Administrator to change your access rights.
+    NotFound:
+      description: Not Found
+      content:
+        application/problem+json:
+          example:
+            [ ]
+
   examples:
     service_status:
       description: List of service information
@@ -1018,6 +1007,7 @@ components:
         service_id: service_id
         keep_alive_interval_seconds: 0
         time_since_last_activity_seconds: 6
+
     service_status_list:
       description: List of service information
       value:
@@ -1072,13 +1062,15 @@ components:
       description: A list of policy identities
       value:
         policy_ids:
-          - policy_ids
-          - policy_ids
+          - some_policy_id
+          - some_policy_id
     policy_status_info:
       description: Status for one A1-P Policy
       value:
         last_modified: last_modified
-        status: "{}"
+        status:
+          value:
+            status: status
     status_info:
       value:
         status: status
@@ -1086,23 +1078,23 @@ components:
       value:
         ric_id: ric_id
         managed_element_ids:
-          - managed_element_ids
-          - managed_element_ids
+          - some_managed_element_id
+          - some_managed_element_id
         state: UNAVAILABLE
         policytype_ids:
-          - policytype_ids
-          - policytype_ids
+          - some_policytype_id
+          - some_policytype_id
     ric_info_list:
       value:
         rics:
           - ric_id: ric_id
             managed_element_ids:
-              - managed_element_ids
-              - managed_element_ids
+              - some_managed_element_id
+              - some_managed_element_id
             state: UNAVAILABLE
             policytype_ids:
-              - policytype_ids
-              - policytype_ids
+              - policytype_id
+              - policytype_id
           - ric_id: ric_id
             managed_element_ids:
               - managed_element_ids
@@ -1111,6 +1103,7 @@ components:
             policytype_ids:
               - policytype_ids
               - policytype_ids
+
   schemas:
     policy_type_definition:
       description: Contains policy type schema definition
@@ -1128,6 +1121,10 @@ components:
             of the problem.'
           example: Policy type not found
           type: string
+        title:
+          description: 'A specific error name'
+          type: string
+          example: Not Found
         status:
           description: 'The HTTP status code generated by the origin server for this
             occurrence of the problem. '
@@ -1370,4 +1367,4 @@ components:
           type: boolean
         href:
           type: string
-      type: object
+      type: object
\ No newline at end of file