From ddf58542c2b20520d3565d8e4feac4951a37aa64 Mon Sep 17 00:00:00 2001 From: BjornMagnussonXA Date: Wed, 6 Oct 2021 11:05:01 +0200 Subject: [PATCH] Updated and corrected sim documentation Issue-ID: NONRTRIC-605 Signed-off-by: BjornMagnussonXA Change-Id: I5ed41be4592482a8c944baaafe032d2b66d8b615 --- docs/simulator-api.rst | 709 ++++++++++++++++++++----------------------------- 1 file changed, 282 insertions(+), 427 deletions(-) diff --git a/docs/simulator-api.rst b/docs/simulator-api.rst index 9e71074..5449252 100644 --- a/docs/simulator-api.rst +++ b/docs/simulator-api.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2020 Nordix +.. Copyright (C) 2021 Nordix .. _simulator-api: @@ -30,14 +30,14 @@ GET Returns the status of the simulator. **URL path:** - / + / **Parameters:** None. **Responses:** 200: - Simulator is living. + OK **Examples:** @@ -49,7 +49,7 @@ Returns the status of the simulator. 200: :: - Simulator is living (OSC_2.1.0 responds OK) + OK Supported Interfaces -------------------- @@ -88,7 +88,7 @@ None. 200: :: - 1.1.x-alpha.2 OSC_2.1.0 STD_1.1.3 + Current interface: STD_2.0.0 All supported A1 interface yamls in this container: ['OSC_2.1.0', 'STD_1.1.3', 'STD_2.0.0'] Counters -------- @@ -101,7 +101,7 @@ The simulator keeps counts of different things that can be accessed. GET +++ -Get a counter. Counter-name can be one of the following: 'num_instances', 'num_types' or 'interface'. +Get a counter. Counter-name can be one of the following: 'num_instances', 'num_types', 'interface', 'remote_hosts' or 'datadelivery'. **URL path:** @@ -129,19 +129,11 @@ The counter value for the given counter. 10 -Version Specific Functions -========================== - -The methods available to control the simulator depends on the version of the A1 API the simulator is simulating. -OSC_2.1.0 ---------- +Reset simulator +--------------- -This section describes the available administrative functions for the OSC_2.1.0 version of A1. - -To see the A1 functions for this version, see `OSC_2.1.0 API`_. - -.. _OSC_2.1.0 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/OSC_2.1.0/openapi.yaml +There are two ways to reset the simulator, delete all instances or make a complete reset which resets the simulator to its original state. /deleteinstances ~~~~~~~~~~~~~~~~ @@ -201,7 +193,7 @@ All policy instances and types deleted. **Examples:** - **Call**: :: +**Call**: :: curl -X POST "http://localhost:8085/deleteall" @@ -211,188 +203,12 @@ All policy instances and types deleted. All policy instances and types deleted. -/policytype -~~~~~~~~~~~ - -PUT -+++ - -Create a policy type. - -**URL path:** - -/policytype?id= - -**Parameters:** - -id: (*Required*) - -The ID of the policy type. - -**Body:** (*Required*) - -A JSON object containing the schema for the type. - -**Responses:** - -200: - -Policy type is OK. - -201: - -Policy type is OK. - -**Examples:** - -**Call**: :: - - curl -X PUT "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - -H "Content-Type: application/json" - -d '{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "STD_PolicyModelUnconstrained_0.2.0", - "description": "Standard model of a policy with unconstrained scope id combinations", - "type": "object", - "properties": { - "scope": { - "type": "object", - "properties": { - "ueId": {"type": "string"}, - "groupId": {"type": "string"}, - "sliceId": {"type": "string"}, - "qosId": {"type": "string"}, - "cellId": {"type": "string"} - }, - "minProperties": 1, - "additionalProperties": false - }, - "qosObjectives": { - "type": "object", - "properties": { - "gfbr": {"type": "number"}, - "mfbr": {"type": "number"}, - "priorityLevel": {"type": "number"}, - "pdb": {"type": "number"} - }, - "additionalProperties": false - }, - "qoeObjectives": { - "type": "object", - "properties": { - "qoeScore": {"type": "number"}, - "initialBuffering": {"type": "number"}, - "reBuffFreq": {"type": "number"}, - "stallRatio": {"type": "number"} - }, - "additionalProperties": false - }, - "resources": { - "type": "array", - "items": { - "type": "object", - "properties": { - "cellIdList": { - "type": "array", - "minItems": 1, - "uniqueItems": true, - "items": { - "type": "string" - } - }, - "preference": { - "type": "string", - "enum": [ - "SHALL", - "PREFER", - "AVOID", - "FORBID" - ] - }, - "primary": {"type": "boolean"} - }, - "additionalProperties": false, - "required": ["cellIdList", "preference"] - } - } - }, - "minProperties": 2, - "additionalProperties": false, - "required": ["scope"] - }' - -**Result**: - -201: :: - - Policy type STD_PolicyModelUnconstrained_0.2.0 is OK +200 :: + All policy instances deleted (Only for STD_1.1.3 since it has no types) -DELETE -++++++ - -Delete a policy type. - -**URL path:** - -/policytype?id= - -**Parameters:** - -id: (*Required*) - -The ID of the policy type. - -**Responses:** - -204: - -Policy type is OK. - -**Examples:** - -**Call**: :: - - curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - -**Result**: - -204: :: - - Policy type STD_PolicyModelUnconstrained_0.2.0 is OK - -/policytypes -~~~~~~~~~~~~ - -GET -+++ - -Get a list of policy types. - -**URL path:** - -/policytypes - -**Parameters:** - -None. - -**Responses:** - -200: - -A list of policy types. - -**Examples:** - -**Call**: :: - - curl -X GET "http://localhost:8085/policytypes" - -**Result**: - -200: :: - - STD_PolicyModelUnconstrained_0.2.0 +Response manipulation +--------------------- +It is possible to manipulate the response of all operations on the A1 interface (admin interface is not affected) /forceresponse ~~~~~~~~~~~~~~ @@ -400,15 +216,15 @@ A list of policy types. POST ++++ -Force a specific response code for an A1 operation. +Force a specific response code for one (the next) A1 operation. After that response, the reponse code will go back to normal. **URL path:** -/forceresponse?responsecode= +/forceresponse?code= **Parameters:** -responsecode: (*Required*) +code: (*Required*) The HTTP response code to return. @@ -422,7 +238,7 @@ Force response code: set for one single A1 response **Call**: :: - curl -X POST "http://localhost:8085/forceresponse?responsecode=400" + curl -X POST "http://localhost:8085/forceresponse?code=400" **Result**: @@ -436,7 +252,7 @@ Force response code: set for one single A1 response POST ++++ -Force delayed response of all A1 operations. +Force delayed response of all A1 responses. The setting will remain until the delay is set to '0' **URL path:** @@ -466,202 +282,275 @@ Force delay: sec set for all A1 responses Force delay: 2 sec set for all A1 responses -/status -~~~~~~~ -PUT -+++ +Configure logging +----------------- +Detailed logging of the http headers and payload are activated by default. However, it is possible to turn this logging on or off. +The 'off' state will only logg ip, url and respose code. -Set status and optional reason, delete and time stamp. +/payload_logging/ +~~~~~~~~~~~~~~~~~ + +POST +++++ +Configure detailed logging on or off **URL path:** -/status?policyid=&status=&deleted=&created_at= +/payload_logging/ **Parameters:** -policyid: (*Required*) - -The ID of a policy. - -status: (*Required*) - -The status of a policy. - -deleted: (*Optional*) +state: (*Required*) -True or false for real values, but accepts anything for error testing. - -created_at: (*Optional*) - -Time stamp for the status. +The state, 'on' or 'off'. **Responses:** 200: -Status set to for policy +Force delay: sec set for all A1 responses **Examples:** **Call**: :: - curl -X PUT "http://localhost:8085/policyid=Policy1&status?status=Accepted + curl -X POST "http://localhost:8085/payload_logging/on" **Result**: 200: :: - Status set to Accepted for policy Policy1. + Payload and header logging set to: on -A1 Standard 1.1.3 ------------------ -This section describes the available administrative functions for the A1 Standard 1.1.3 version of A1. +Version Specific Functions +========================== -To see the A1 functions for this version, see `A1 Standard 1.1.3 API`_. +The methods available to control the simulator depends on the version of the A1 API the simulator is simulating. -.. _A1 Standard 1.1.3 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/STD_1.1.3/STD_A1.yaml +OSC_2.1.0 +--------- -/deleteinstances -~~~~~~~~~~~~~~~~ +This section describes the available administrative functions for the OSC_2.1.0 version of A1. -POST -++++ +To see the A1 functions for this version, see `OSC_2.1.0 API`_. -Delete all policy instances. +.. _OSC_2.1.0 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/OSC_2.1.0/openapi.yaml + + + +/policytype +~~~~~~~~~~~ + +PUT ++++ + +Create a policy type. **URL path:** -/deleteinstances +/policytype?id= **Parameters:** -None. +id: (*Required*) + +The ID of the policy type. + +**Body:** (*Required*) + +A JSON object containing the schema for the type. **Responses:** 200: -All policy instances deleted. +Policy type is OK. + +201: + +Policy type is OK. **Examples:** **Call**: :: - curl -X POST "http://localhost:8085/deleteinstances" + curl -X PUT "http://localhost:8085/policytype?id=1" + -H "Content-Type: application/json" + -d '{ + "name": "pt1", + "description": "pt1 policy type", + "policy_type_id": 1, + "create_schema": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "STD_QoSNudging_0.2.0", + "description": "QoS policy type", + "type": "object", + "properties": { + "scope": { + "type": "object", + "properties": { + "ueId": { + "type": "string" + }, + "qosId": { + "type": "string" + } + }, + "additionalProperties": false, + "required": [ + "ueId", + "qosId" + ] + }, + "statement": { + "type": "object", + "properties": { + "priorityLevel": { + "type": "number" + } + }, + "additionalProperties": false, + "required": [ + "priorityLevel" + ] + } + } + } + }' **Result**: -200: :: - - All policy instances deleted. +201: :: -/deleteall -~~~~~~~~~~ + Policy type 1 is OK -POST -++++ +DELETE +++++++ -Full reset. +Delete a policy type. **URL path:** -/deleteinstances +/policytype?id= **Parameters:** -None. +id: (*Required*) + +The ID of the policy type. **Responses:** -200: +204: -All policy instances deleted. +Policy type is OK. **Examples:** **Call**: :: - curl -X POST "http://localhost:8085/deleteall" + curl -X DELETE "http://localhost:8085/policytype?id=1" **Result**: -200: :: +204 - All policy instances deleted. -/forceresponse -~~~~~~~~~~~~~~ -POST -++++ +/policytypes +~~~~~~~~~~~~ + +GET ++++ -Force a specific response code for an A1 operation. +Get a list of policy types. **URL path:** -/forceresponse?responsecode= +/policytypes **Parameters:** -responsecode: (*Required*) - -The HTTP response code to return. +None. **Responses:** 200: -Force response code: set for one single A1 response +A list of policy types. **Examples:** **Call**: :: - curl -X POST "http://localhost:8085/forceresponse?responsecode=400" + curl -X GET "http://localhost:8085/policytypes" **Result**: 200: :: - Force response code: 400 set for one single A1 response + ["1"] -/forcedelay -~~~~~~~~~~~ -POST -++++ +/status +~~~~~~~ -Force delayed response of all A1 operations. +PUT ++++ + +Set status and optional reason, delete and time stamp. **URL path:** -/forcedelay?delay= +/status?policyid=&status=&deleted=&created_at= **Parameters:** -delay: (*Required*) +policyid: (*Required*) -The time in seconds to delay all responses. +The ID of a policy. + +status: (*Required*) + +The status of a policy. + +deleted: (*Optional*) + +True or false for real values, but accepts anything for error testing. + +created_at: (*Optional*) + +Time stamp for the status. **Responses:** 200: -Force delay: sec set for all A1 responses +Status set to for policy **Examples:** **Call**: :: - curl -X POST "http://localhost:8085/forcedelay?delay=2" + curl -X PUT "http://localhost:8085/status?policyid=1&status=Accepted" **Result**: 200: :: - Force delay: 2 sec set for all A1 responses + Status set to Accepted for policy Policy1. + +A1 Standard 1.1.3 +----------------- + +This section describes the available administrative functions for the A1 Standard 1.1.3 version of A1. + +To see the A1 functions for this version, see `A1 Standard 1.1.3 API`_. + +.. _A1 Standard 1.1.3 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/STD_1.1.3/STD_A1.yaml + /status ~~~~~~~ @@ -699,7 +588,7 @@ Status set to for policy **Call**: :: - curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted + curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted" **Result**: @@ -741,60 +630,130 @@ Is a JSON with the response of the actual post request to the callback server, w 200 -1.1.x-alpha.2 -------------- -This section describes the available administrative functions for the 1.1.x-alpha.2 version of A1. +A1 Standard 2.0.0 +----------------- -To see the A1 functions for this version, see `1.1.x-alpha.2 API`_. +This section describes the available administrative functions for the A1 Standard 2.0.0 version of A1. -.. _1.1.x-alpha.2 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/1.1.x-alpha.2/a1-openapi.yaml +To see the A1 functions for this version, see `A1 Standard 2.0.0 API`_. -/deleteinstances -~~~~~~~~~~~~~~~~ +.. _A1 Standard 2.0.0 API: https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=blob;f=near-rt-ric-simulator/api/STD_2.0.0/ORAN_A1-p_V2.0.0_api.yaml -DELETE -++++++ -Delete all policy instances. +/policytype +~~~~~~~~~~~ + +PUT ++++ + +Create or update a policy type. **URL path:** -/deleteinstances +/policytype?id={policy-type-id} **Parameters:** -None. +policy-type-id: (*Required*) + +The ID of the policy type. + +**Body:** (*Required*) + +A JSON object containing the schema for the type. **Responses:** 200: -All policy instances deleted. +The policy type is ok + +201: + +The policy type is ok **Examples:** **Call**: :: - curl -X DELETE "http://localhost:8085/deleteinstances" + curl -X PUT "http://localhost:8085/policytype?id=STD_PolicyModelUnconstrained_0.2.0" + -H "Content-Type: application/json" + -d '{ + "policySchema": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "STD_1_0.2.0", + "description": "STD 1 policy type", + "type": "object", + "properties": { + "scope": { + "type": "object", + "properties": { + "ueId": { + "type": "string" + }, + "qosId": { + "type": "string" + } + }, + "additionalProperties": false, + "required": [ + "ueId", + "qosId" + ] + }, + "statement": { + "type": "object", + "properties": { + "priorityLevel": { + "type": "number" + } + }, + "additionalProperties": false, + "required": [ + "priorityLevel" + ] + } + } + }, + "statusSchema": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "STD_1_0.2.0", + "description": "STD 1 policy type status", + "type": "object", + "properties": { + "enforceStatus": { + "type": "string" + }, + "enforceReason": { + "type": "string" + }, + "additionalProperties": false, + "required": [ + "enforceStatus" + ] + } + } + }' **Result**: 200: :: - All policy instances deleted. + Policy type STD_PolicyModelUnconstrained_0.2.0 is OK -/deletetypes -~~~~~~~~~~~~ +201: :: + + Policy type STD_PolicyModelUnconstrained_0.2.0 is OK DELETE ++++++ -Delete all policy types. +Delete a policy type. **URL path:** -/deletetypes +/policytype?id={policy-type-id} **Parameters:** @@ -802,162 +761,55 @@ None. **Responses:** -200: +204 -All policy types deleted. **Examples:** **Call**: :: - curl -X DELETE "http://localhost:8085/deletetypes" + curl -X DELETE "http://localhost:8085/policytype?id=STD_PolicyModelUnconstrained_0.2.0" **Result**: -200: :: +204 + - All policy types deleted. /policytypes ~~~~~~~~~~~~ -PUT +GET +++ -Create or update a policy type. +Get a list of policy types. **URL path:** -/policytypes/{policy-type-id} +/policytypes **Parameters:** None. -**Body:** (*Required*) - -A JSON object containing the schema for the type. - **Responses:** 200: -The policy type was either created or updated for policy type id: +A list of policy types. **Examples:** **Call**: :: - curl -X PUT "http://localhost:8085/policytype/Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - -H "Content-Type: application/json" - -d '{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "STD_PolicyModelUnconstrained_0.2.0", - "description": "Standard model of a policy with unconstrained scope id combinations", - "type": "object", - "properties": { - "scope": { - "type": "object", - "properties": { - "ueId": {"type": "string"}, - "groupId": {"type": "string"}, - "sliceId": {"type": "string"}, - "qosId": {"type": "string"}, - "cellId": {"type": "string"} - }, - "minProperties": 1, - "additionalProperties": false - }, - "qosObjectives": { - "type": "object", - "properties": { - "gfbr": {"type": "number"}, - "mfbr": {"type": "number"}, - "priorityLevel": {"type": "number"}, - "pdb": {"type": "number"} - }, - "additionalProperties": false - }, - "qoeObjectives": { - "type": "object", - "properties": { - "qoeScore": {"type": "number"}, - "initialBuffering": {"type": "number"}, - "reBuffFreq": {"type": "number"}, - "stallRatio": {"type": "number"} - }, - "additionalProperties": false - }, - "resources": { - "type": "array", - "items": { - "type": "object", - "properties": { - "cellIdList": { - "type": "array", - "minItems": 1, - "uniqueItems": true, - "items": { - "type": "string" - } - }, - "preference": { - "type": "string", - "enum": [ - "SHALL", - "PREFER", - "AVOID", - "FORBID" - ] - }, - "primary": {"type": "boolean"} - }, - "additionalProperties": false, - "required": ["cellIdList", "preference"] - } - } - }, - "minProperties": 2, - "additionalProperties": false, - "required": ["scope"] - }' + curl -X GET "http://localhost:8085/policytypes" **Result**: 200: :: - The policy type was either created or updated for policy type id: STD_PolicyModelUnconstrained_0.2.0 - -DELETE -++++++ - -Delete a policy type. - -**URL path:** - -/policytypes/{policy-type-id} - -**Parameters:** - -None. - -**Responses:** - -200: - -policy type successfully deleted for policy type id: - -**Examples:** - -**Call**: :: - - curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - -**Result**: - -200: :: + ["STD_PolicyModelUnconstrained_0.2.0"] - policy type successfully deleted for policy type id: STD_PolicyModelUnconstrained_0.2.0 /{policyId}/{enforceStatus} ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -969,7 +821,7 @@ Set a status to a policy instance with an enforceStatus parameter only. **URL path:** -/{policyId}/{enforceStatus} +/status?policyid={policyId}&status={status}&reason={reason} **Parameters:** @@ -985,7 +837,7 @@ Status updated for policy: **Call**: :: - curl -X PUT "http://localhost:8085/Policy1/ENFORCED + curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=ENFORCED" **Result**: @@ -996,33 +848,36 @@ Status updated for policy: /{policyId}/{enforceStatus}/{enforceReason} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -PUT +/sendstatus +~~~~~~~~~~~ + +POST ++++ -Send a status to a policy instance with both enforceStatus and enforceReason. +Send status for policy. **URL path:** -/{policyId}/{enforceStatus}/{enforceReason} +/sendstatus?policyid= **Parameters:** -None. +policyid: (*Required*) + +The ID of the policy to send status for. **Responses:** 200: -Status updated for policy: +Is a JSON with the response of the actual post request to the callback server, whatever that is. **Examples:** **Call**: :: - curl -X PUT "http://localhost:8085/Policy1/NOT_ENFORCED/100" + curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2" **Result**: -200: :: - - Status updated for policy: Policy1 +200 -- 2.16.6