# ==================================================================================
openapi: 3.0.0
info:
- version: 0.9.0
+ version: 1.0.0
title: RIC A1
paths:
'/a1-p/healthcheck':
get:
description: >
- perform a healthcheck on a1
+ Perform a healthcheck on a1
tags:
- A1 Mediator
- operationId: a1.controller.healthcheck_handler
+ operationId: a1.controller.get_healthcheck
responses:
200:
description: >
- a1 is healthy. Anything other than a 200 should be considered a1 as failing
+ A1 is healthy.
+ Anything other than a 200 should be considered a1 as failing
- '/ric/policies/{policyname}':
+ '/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"
- 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.
+ '/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"]
- Eventually, we need concrete policy defintions that are decoupled from xapp, and then this API description will become more fully specified.
+ '/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.put_handler
+ 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
+
+ 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.
+
+ tags:
+ - A1 Mediator
+ 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:
'200':
description: >
- The downstream component responsible for implementing this policy replied with a good response. Check the manifest for response details.
- '400':
- description: >
- The downstream component for implementing this policy does not support policy fetching.
+ successfully retrieved the status
+ content:
+ text/plain:
+ schema:
+ type: string
+ enum:
+ - IN EFFECT
+ - NOT IN EFFECT
'404':
description: >
- there is no policy with this name
- '504':
+ 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: >
- the downstream component responsible for handling this policy did not respond (in time)
+ 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
Code Review / ric-plt / a1.git / blobdiff