X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=a1%2Fopenapi.yaml;h=fed4b77546264cc8a390504dae725ca15060d81a;hb=a0876efd819b43b870ba2254b34676b1a03ad326;hp=aa02cc698e3ffcb5055197d56827a213b58e7765;hpb=5ad8f03e1fc7683bb59da31f59edc2f6c0b2372b;p=ric-plt%2Fa1.git

diff --git a/a1/openapi.yaml b/a1/openapi.yaml
index aa02cc6..fed4b77 100644
--- a/a1/openapi.yaml
+++ b/a1/openapi.yaml
@@ -1,77 +1,387 @@
+# ==================================================================================
+#       Copyright (c) 2019 Nokia
+#       Copyright (c) 2018-2019 AT&T Intellectual Property.
+#
+#   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.
+# ==================================================================================
 openapi: 3.0.0
 info:
-  version: 0.8.0
+  version: 1.0.0
   title: RIC A1
 paths:
-  '/ric/policies/{policyname}':
+  '/a1-p/healthcheck':
+    get:
+      description: >
+        Perform a healthcheck on a1
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.get_healthcheck
+      responses:
+        200:
+          description: >
+            A1 is healthy.
+            Anything other than a 200 should be considered a1 as failing
+
+  '/a1-p/policytypes':
+    get:
+      description: "Get a list of all registered policy type ids"
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.get_all_policy_types
+      responses:
+        200:
+          description: "list of all registered policy type ids"
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  "$ref": "#/components/schemas/policy_type_id"
+              example: [20000, 20020]
+
+  '/a1-p/policytypes/{policy_type_id}':
     parameters:
-      - name: policyname
+      - name: policy_type_id
         in: path
-        description: the name of the policy to retrieve or replace
         required: true
         schema:
-          type: string
+          "$ref": "#/components/schemas/policy_type_id"
+    get:
+      description: >
+        Get this policy type
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.get_policy_type
+      responses:
+        '200':
+          description: "policy type successfully found"
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/policy_type_schema"
+        '404':
+          description: >
+            policy type not found
+    delete:
+      description: >
+        Delete this policy type. Can only be performed if there are no instances of this type
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.delete_policy_type
+      responses:
+        '204':
+          description: >
+            policy type successfully deleted
+        '400':
+          description: >
+            Policy type cannot be deleted because there are instances
+            All instances must be removed before a policy type can be deleted
+        '404':
+          description: >
+            policy type not found
     put:
       description: >
-          Replace the current operation of policyname with the new parameters (replaces the current policy with the new one specified here).
+        Create a new policy type .
+        Replace is not currently allowed; to replace, for now do a DELETE and then a PUT again.
+
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.create_policy_type
+      requestBody:
+        content:
+          application/json:
+            schema:
+               "$ref": "#/components/schemas/policy_type_schema"
+            example:
+              name: admission_control_policy
+              description: various parameters to control admission of dual connection
+              policy_type_id: 20000
+              create_schema:
+                $schema: 'http://json-schema.org/draft-07/schema#'
+                type: object
+                properties:
+                  enforce:
+                    type: boolean
+                    default: true
+                  window_length:
+                    type: integer
+                    default: 1
+                    minimum: 1
+                    maximum: 60
+                    description: Sliding window length (in minutes)
+                  blocking_rate:
+                    type: number
+                    default: 10
+                    minimum: 1
+                    maximum: 100
+                    description: '% Connections to block'
+                  trigger_threshold:
+                    type: integer
+                    default: 10
+                    minimum: 1
+                    description: Minimum number of events in window to trigger blocking
+                additionalProperties: false
+
+      responses:
+        '201':
+          description: "policy type successfully created"
+        '400':
+          description: "illegal ID, or object already existed"
+
+  '/a1-p/policytypes/{policy_type_id}/policies':
+    parameters:
+      - name: policy_type_id
+        in: path
+        required: true
+        schema:
+          "$ref": "#/components/schemas/policy_type_id"
+    get:
+      description: "get a list of all policy instance ids for this policy type id"
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.get_all_instances_for_type
+      responses:
+        200:
+          description: "list of all policy instance ids for this policy type id"
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  "$ref": "#/components/schemas/policy_instance_id"
+              example: ["3d2157af-6a8f-4a7c-810f-38c2f824bf12", "06911bfc-c127-444a-8eb1-1bffad27cc3d"]
+
+
+  '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}':
+    parameters:
+      - name: policy_type_id
+        in: path
+        required: true
+        schema:
+          "$ref": "#/components/schemas/policy_type_id"
+
+      - name: policy_instance_id
+        in: path
+        required: true
+        schema:
+          "$ref": "#/components/schemas/policy_instance_id"
+
+    get:
+      description: >
+        Retrieve the policy instance
 
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.get_policy_instance
+      responses:
+        '200':
+          description: >
+            The policy instance.
+            the schema of this object is defined by the create_schema field of the policy type
+          content:
+            application/json:
+              schema:
+                type: object
+        '404':
+          description: >
+            there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
+
+    delete:
+      description: >
+        Delete this policy instance
 
-          Until there are standard policy definitions that are defined OUTSIDE of the scope of xapps, this API will be *very underspecified*.
-          This is a known gap, do not despair.
-          The PUT body is specified, *currently* in the xapp manifest that implements this policy; the caller should refer to the message_receives_payload_schema field to make this request.
-          The return content is also specified as above (in the xapp manifest) in the message_sends_payload_schema field.
+      tags:
+        - A1 Mediator
+      operationId: a1.controller.delete_policy_instance
+      responses:
+        '202':
+          description: >
+            policy instance deletion initiated
+        '404':
+          description: >
+            there is no policy instance with this policy_instance_id
+            or there is no policy type with this policy_type_id
 
+    put:
+      description: >
+        Create or replace a policy instance of type policy_type_id.
+        The schema of the PUT body is defined by the create_schema field of the policy type.
 
-          Eventually, we need concrete policy defintions that are decoupled from xapp, and then this API description will become more fully specified.
       tags:
         - A1 Mediator
-      operationId: a1.controller.put_handler
+      operationId: a1.controller.create_or_replace_policy_instance
       requestBody:
         content:
           application/json:
             schema:
               type: object
-
+              description: >
+                  the schema of this object is defined by the create_schema field of the policy type
+            example:
+              enforce: true
+              window_length: 10
+              blocking_rate: 20
+              trigger_threshold: 10
 
       responses:
-        '200':
+        '202':
           description: >
-            The downstream component responsible for implementing this policy replied with a good response. Check the manifest for response details.
+            Policy instance creation initiated
         '400':
           description: >
-            Bad PUT body for this policyname
+            Bad PUT body for this policy instance
         '404':
           description: >
-            there is no policy with this name
-        '502':
-          description: >
-            The xapp that implements this policy replied, but the reply was a "failure", OR there was no status indicating success or failure.
-            This returns an object containing the reason, and the return payload.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  reason:
-                    type: string
-                    enum: [
-                        "NO STATUS",
-                        "BAD STATUS",
-                        "NOT JSON"
-                    ]
-                  return_payload:
-                    type: object
+            There is no policy type with this policy_type_id
 
-        '504':
-          description: >
-            the downstream component responsible for handling this policy did not respond (in time)
+  '/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}/status':
+    parameters:
+      - name: policy_type_id
+        in: path
+        required: true
+        schema:
+          "$ref": "#/components/schemas/policy_type_id"
+
+      - name: policy_instance_id
+        in: path
+        required: true
+        schema:
+          "$ref": "#/components/schemas/policy_instance_id"
 
     get:
-      description: Get the current state/value of policyname
+      description: >
+        Retrieve the policy instance status across all handlers of the policy
+        If this endpoint returns successfully (200), it is either IN EFFECT or NOT IN EFFECT.
+        IN EFFECT is returned if at least one policy handler in the RIC is implementing the policy
+        NOT IN EFFECT is returned otherwise
+        If a policy instance is successfully deleted, this endpoint will return a 404 (not a 200)
       tags:
         - A1 Mediator
-      operationId: a1.controller.get_handler
+      operationId: a1.controller.get_policy_instance_status
       responses:
-        '501':
+        '200':
           description: >
-            "future GET support has been pondered, but this is not currently implemented"U
+            successfully retrieved the status
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                 - IN EFFECT
+                 - NOT IN EFFECT
+        '404':
+          description: >
+            there is no policy instance with this policy_instance_id or there is no policy type with this policy_type_id
+
+components:
+  schemas:
+    policy_type_schema:
+      type: object
+      required:
+      - name
+      - description
+      - policy_type_id
+      - create_schema
+      additionalProperties: false
+      properties:
+        name:
+          type: string
+          description: name of the policy type
+        description:
+          type: string
+          description: description of the policy type
+        policy_type_id:
+          description: the integer of the policy type
+          type: integer
+        create_schema:
+          type: object
+          description: >
+            jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload to be sent to handlers of this policy
+
+    policy_type_id:
+      description: >
+        represents a policy type identifier. Currently this is restricted to an integer range.
+      type: integer
+      minimum: 20000
+      maximum: 21023
+
+    policy_instance_id:
+      description: >
+        represents a policy instance identifier. UUIDs are advisable but can be any string
+      type: string
+      example: "3d2157af-6a8f-4a7c-810f-38c2f824bf12"
+
+    downstream_message_schema:
+      type: object
+      required:
+        - operation
+        - policy_type_id
+        - policy_instance_id
+        - payload
+      additionalProperties: false
+      properties:
+        operation:
+          description: the operation being performed
+          type: string
+          enum:
+            - CREATE
+            - DELETE
+            - UPDATE
+            - READ
+        policy_type_id:
+          "$ref": "#/components/schemas/policy_type_id"
+        policy_instance_id:
+          "$ref": "#/components/schemas/policy_instance_id"
+        payload:
+          description: payload for this operation
+          type: object
+      example:
+        operation: CREATE
+        policy_type_id: 12345678
+        policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
+        payload:
+          enforce: true
+          window_length: 10
+          blocking_rate: 20
+          trigger_threshold: 10
+
+    downstream_notification_schema:
+      type: object
+      required:
+        - policy_type_id
+        - policy_instance_id
+        - handler_id
+        - status
+      additionalProperties: false
+      properties:
+        policy_type_id:
+          "$ref": "#/components/schemas/policy_type_id"
+        policy_instance_id:
+          "$ref": "#/components/schemas/policy_instance_id"
+        handler_id:
+          description: >
+            id of the policy handler
+          type: string
+        status:
+          description: >
+            the status of this policy instance in this handler
+          type: string
+          enum:
+            - OK
+            - ERROR
+            - DELETED
+      example:
+        policy_type_id: 12345678
+        policy_instance_id: 3d2157af-6a8f-4a7c-810f-38c2f824bf12
+        handler_id: 1234-5678
+        status: OK