From c67ef9d7139f36c3fdfdd3e75e005b24f356bf7e Mon Sep 17 00:00:00 2001 From: elinuxhenrik Date: Mon, 20 Apr 2020 17:05:00 +0200 Subject: [PATCH] Fixed formatting of API documentation Change-Id: Ieeb03552c1c7beefb314faf16e89e59067a4bc48 Issue-ID: NONRTRIC-158 Signed-off-by: elinuxhenrik --- docs/simulator-api.rst | 769 +++++++++++++++++++++++-------------------------- 1 file changed, 354 insertions(+), 415 deletions(-) diff --git a/docs/simulator-api.rst b/docs/simulator-api.rst index bb23da3..4e37deb 100644 --- a/docs/simulator-api.rst +++ b/docs/simulator-api.rst @@ -13,10 +13,6 @@ This document describes the API used to manage policy types and manipulate the s The simulator supports different versions of the A1 interface. Some functions are common for all version, and some are specific for a certain version. -.. contents:: Operations - :depth: 4 - :local: - Common Functions ================ @@ -31,29 +27,27 @@ The status of the simulator. GET +++ - Returns the status of the simulator. - - **URL path:** - / - - **Parameters:** +Returns the status of the simulator. - None. +**URL path:** + / - **Responses:** +**Parameters:** + None. - 200: - Simulator is living. +**Responses:** + 200: + Simulator is living. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X GET "http://localhost:8085/" - curl -X GET "http://localhost:8085/" + Result: + 200: :: - Result: - 200 - Simulator is living (OSC_2.1.0 responds OK) + Simulator is living (OSC_2.1.0 responds OK) Supported Interfaces -------------------- @@ -66,29 +60,27 @@ The simulator can support different versions of the A1 interface. With this API GET +++ - Returns the status of the simulator. (Not available for A1 Standard 1.1.3) - - **URL path:** - /container_interfaces - - **Parameters:** +Returns the status of the simulator. (Not available for A1 Standard 1.1.3) - None. +**URL path:** + /container_interfaces - **Responses:** +**Parameters:** + None. - 200: - List of supported interfaces. +**Responses:** + 200: + List of supported interfaces. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X GET "http://localhost:8085/container_interfaces" - curl -X GET "http://localhost:8085/container_interfaces" + Result: + 200: :: - Result: - 200 - 1.1.x-alpha.2 OSC_2.1.0 STD_1.1.3 + 1.1.x-alpha.2 OSC_2.1.0 STD_1.1.3 Counters -------- @@ -101,29 +93,27 @@ 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' or 'interface'. - **URL path:** - /counter/{counter-name} +**URL path:** + /counter/{counter-name} - **Parameters:** +**Parameters:** + None. - None. +**Responses:** + 200: + The counter value for the given counter. - **Responses:** +**Examples:** + **Call**: :: - 200: - The counter value for the given counter. + curl -X GET "http://localhost:8085/counter/num_instances" - **Examples:** + Result: + 200: :: - Call: :: - - curl -X GET "http://localhost:8085/counter/num_instances" - - Result: - 200 - 10 + 10 Version Specific Functions ========================== @@ -141,29 +131,27 @@ The available functions for the OSC_2.1.0 version of A1. POST ++++ - Delete all policy instances. - - **URL path:** - /deleteinstances - - **Parameters:** +Delete all policy instances. - None. +**URL path:** + /deleteinstances - **Responses:** +**Parameters:** + None. - 200: - All policy instances deleted. +**Responses:** + 200: + All policy instances deleted. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X POST "http://localhost:8085/deleteinstances" - curl -X POST "http://localhost:8085/deleteinstances" + Result: + 200: :: - Result: - 200 - All policy instances deleted. + All policy instances deleted. /deleteall ~~~~~~~~~~~~~~~~ @@ -171,29 +159,27 @@ POST POST ++++ - Full reset. - - **URL path:** - /deleteall +Full reset. - **Parameters:** +**URL path:** + /deleteall - None. +**Parameters:** + None. - **Responses:** - - 200: - All policy instances and types deleted. +**Responses:** + 200: + All policy instances and types deleted. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X POST "http://localhost:8085/deleteall" - curl -X POST "http://localhost:8085/deleteall" + Result: + 200: :: - Result: - 200 - All policy instances and types deleted. + All policy instances and types deleted. /policytype ~~~~~~~~~~~ @@ -201,35 +187,30 @@ POST PUT +++ - Create a policy type. - - **URL path:** - /policytype?id= - - **Parameters:** - - id: (*Required*) - The ID of the policy type. +Create a policy type. - **Body:** (*Required*) - A JSON object containing the schema for the type. +**URL path:** + /policytype?id= - **Responses:** +**Parameters:** + id: (*Required*) + The ID of the policy type. - 200: - Policy type is OK. +**Body:** (*Required*) + A JSON object containing the schema for the type. - 201: - Policy type is OK. +**Responses:** + 200: + Policy type is OK. + 201: + Policy type is OK. - **Examples:** +**Examples:** + **Call**: :: - 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 " - { + 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", @@ -299,40 +280,38 @@ PUT "minProperties": 2, "additionalProperties": false, "required": ["scope"] - } - " + }' + + Result: + 201: :: - Result: - 201 - Policy type STD_PolicyModelUnconstrained_0.2.0 is OK + Policy type STD_PolicyModelUnconstrained_0.2.0 is OK DELETE ++++++ - Delete a policy type. - - **URL path:** - /policytype?id= +Delete a policy type. - **Parameters:** +**URL path:** + /policytype?id= - id: (*Required*) - The ID of the policy type. +**Parameters:** + id: (*Required*) + The ID of the policy type. - **Responses:** +**Responses:** + 204: + Policy type is OK. - 204: - Policy type is OK. +**Examples:** + **Call**: :: - **Examples:** + curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - Call: :: + Result: + 204: :: - 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 + Policy type STD_PolicyModelUnconstrained_0.2.0 is OK /policytypes ~~~~~~~~~~~~ @@ -340,29 +319,27 @@ DELETE GET +++ - Get a list of policy types. - - **URL path:** - /policytypes +Get a list of policy types. - **Parameters:** +**URL path:** + /policytypes - None. +**Parameters:** + None. - **Responses:** +**Responses:** + 200: + A list of policy types. - 200: - A list of policy types. +**Examples:** + **Call**: :: - **Examples:** + curl -X GET "http://localhost:8085/policytypes" - Call: :: + Result: + 200: :: - curl -X GET "http://localhost:8085/policytypes" - - Result: - 200 - STD_PolicyModelUnconstrained_0.2.0 + STD_PolicyModelUnconstrained_0.2.0 /forceresponse ~~~~~~~~~~~~~~ @@ -370,30 +347,28 @@ GET POST ++++ - Force a specific response code for an A1 operation. - - **URL path:** - /forceresponse?responsecode= +Force a specific response code for an A1 operation. - **Parameters:** +**URL path:** + /forceresponse?responsecode= - responsecode: (*Required*) - The HTTP response code to return. +**Parameters:** + responsecode: (*Required*) + The HTTP response code to return. - **Responses:** +**Responses:** + 200: + Force response code: set for one single A1 response - 200: - Force response code: set for one single A1 response +**Examples:** + **Call**: :: - **Examples:** + curl -X POST "http://localhost:8085/forceresponse?responsecode=400" - Call: :: + Result: + 200: :: - curl -X POST "http://localhost:8085/forceresponse?responsecode=400" - - Result: - 200 - Force response code: 400 set for one single A1 response + Force response code: 400 set for one single A1 response /forcedelay ~~~~~~~~~~~ @@ -401,30 +376,28 @@ POST POST ++++ - Force delayed response of all A1 operations. - - **URL path:** - /forcedelay?delay= +Force delayed response of all A1 operations. - **Parameters:** +**URL path:** + /forcedelay?delay= - delay: (*Required*) - The time in seconds to delay all responses. +**Parameters:** + delay: (*Required*) + The time in seconds to delay all responses. - **Responses:** +**Responses:** + 200: + Force delay: sec set for all A1 responses - 200: - Force delay: sec set for all A1 responses +**Examples:** + **Call**: :: - **Examples:** + curl -X POST "http://localhost:8085/forcedelay?delay=2" - Call: :: + Result: + 200: :: - curl -X POST "http://localhost:8085/forcedelay?delay=2" - - Result: - 200 - Force delay: 2 sec set for all A1 responses + Force delay: 2 sec set for all A1 responses /status ~~~~~~~ @@ -432,39 +405,34 @@ POST PUT +++ - Set status and optional reason, delete and time stamp. - - **URL path:** - /status?policyid=&status=&deleted=&created_at= - - **Parameters:** - - policyid: (*Required*) - The ID of a policy. +Set status and optional reason, delete and time stamp. - status: (*Required*) - The status of a policy. +**URL path:** + /status?policyid=&status=&deleted=&created_at= - deleted: (*Optional*) - True or false for real values, but accepts anything for error testing. +**Parameters:** + policyid: (*Required*) + 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. - created_at: (*Optional*) - Time stamp for the status. +**Responses:** + 200: + Status set to for policy - **Responses:** +**Examples:** + **Call**: :: - 200: - Status set to for policy + curl -X PUT "http://localhost:8085/policyid=Policy1&status?status=Accepted - **Examples:** + Result: + 200: :: - Call: :: - - curl -X PUT "http://localhost:8085/policyid=Policy1&status?status=Accepted - - Result: - 200 - Status set to Accepted for policy Policy1. + Status set to Accepted for policy Policy1. A1 Standard 1.1.3 ----------------- @@ -477,29 +445,27 @@ The available functions for the A1 Standard 1.1.3 version of A1. POST ++++ - Delete all policy instances. - - **URL path:** - /deleteinstances - - **Parameters:** +Delete all policy instances. - None. +**URL path:** + /deleteinstances - **Responses:** +**Parameters:** + None. - 200: - All policy instances deleted. +**Responses:** + 200: + All policy instances deleted. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X POST "http://localhost:8085/deleteinstances" - curl -X POST "http://localhost:8085/deleteinstances" + Result: + 200: :: - Result: - 200 - All policy instances deleted. + All policy instances deleted. /deleteall ~~~~~~~~~~ @@ -507,29 +473,27 @@ POST POST ++++ - Full reset. - - **URL path:** - /deleteinstances +Full reset. - **Parameters:** +**URL path:** + /deleteinstances - None. +**Parameters:** + None. - **Responses:** - - 200: - All policy instances deleted. +**Responses:** + 200: + All policy instances deleted. - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X POST "http://localhost:8085/deleteall" - curl -X POST "http://localhost:8085/deleteall" + Result: + 200: :: - Result: - 200 - All policy instances deleted. + All policy instances deleted. /forceresponse ~~~~~~~~~~~~~~ @@ -537,30 +501,28 @@ POST POST ++++ - Force a specific response code for an A1 operation. - - **URL path:** - /forceresponse?responsecode= +Force a specific response code for an A1 operation. - **Parameters:** +**URL path:** + /forceresponse?responsecode= - responsecode: (*Required*) - The HTTP response code to return. +**Parameters:** + responsecode: (*Required*) + The HTTP response code to return. - **Responses:** +**Responses:** + 200: + Force response code: set for one single A1 response - 200: - Force response code: set for one single A1 response +**Examples:** + **Call**: :: - **Examples:** + curl -X POST "http://localhost:8085/forceresponse?responsecode=400" - Call: :: + Result: + 200: :: - curl -X POST "http://localhost:8085/forceresponse?responsecode=400" - - Result: - 200 - Force response code: 400 set for one single A1 response + Force response code: 400 set for one single A1 response /forcedelay ~~~~~~~~~~~ @@ -568,30 +530,28 @@ POST POST ++++ - Force delayed response of all A1 operations. - - **URL path:** - /forcedelay?delay= +Force delayed response of all A1 operations. - **Parameters:** +**URL path:** + /forcedelay?delay= - delay: (*Required*) - The time in seconds to delay all responses. +**Parameters:** + delay: (*Required*) + The time in seconds to delay all responses. - **Responses:** +**Responses:** + 200: + Force delay: sec set for all A1 responses - 200: - Force delay: sec set for all A1 responses +**Examples:** + **Call**: :: - **Examples:** + curl -X POST "http://localhost:8085/forcedelay?delay=2" - Call: :: + Result: + 200: :: - curl -X POST "http://localhost:8085/forcedelay?delay=2" - - Result: - 200 - Force delay: 2 sec set for all A1 responses + Force delay: 2 sec set for all A1 responses /status ~~~~~~~ @@ -599,36 +559,32 @@ POST PUT +++ - Set status and optional reason, delete and time stamp. - - **URL path:** - /status?policyid=&status=&reason= - - **Parameters:** - - policyid: (*Required*) - The ID of a policy. - - status: (*Required*) - The status of a policy. +Set status and optional reason, delete and time stamp. - reason: (*Optional*) - The reason for the status. +**URL path:** + /status?policyid=&status=&reason= - **Responses:** +**Parameters:** + policyid: (*Required*) + The ID of a policy. + status: (*Required*) + The status of a policy. + reason: (*Optional*) + The reason for the status. - 200: - Status set to for policy +**Responses:** + 200: + Status set to for policy - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted - curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted + Result: + 200: :: - Result: - 200 - Status set to Accepted for policy Policy1 + Status set to Accepted for policy Policy1 /sendstatus ~~~~~~~~~~~ @@ -636,29 +592,26 @@ PUT POST ++++ - Send status for policy. +Send status for policy. - **URL path:** - /sendstatus?policyid= +**URL path:** + /sendstatus?policyid= - **Parameters:** +**Parameters:** + policyid: (*Required*) + The ID of the policy to send status for. - policyid: (*Required*) - The ID of the policy to send status for. +**Responses:** + 200: + Is a JSON with the response of the actual post request to the callback server, whatever that is. - **Responses:** +**Examples:** + **Call**: :: - 200: - Is a JSON with the response of the actual post request to the callback server, whatever that is. + curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2" - **Examples:** - - Call: :: - - curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2" - - Result: - 200 + Result: + 200 1.1.x-alpha.2 ------------- @@ -671,29 +624,27 @@ The available functions for the 1.1.x-alpha.2. DELETE ++++++ - Delete all policy instances. +Delete all policy instances. - **URL path:** - /deleteinstances +**URL path:** + /deleteinstances - **Parameters:** +**Parameters:** + None. - None. +**Responses:** + 200: + All policy instances deleted. - **Responses:** +**Examples:** + **Call**: :: - 200: - All policy instances deleted. + curl -X DELETE "http://localhost:8085/deleteinstances" - **Examples:** + Result: + 200: :: - Call: :: - - curl -X DELETE "http://localhost:8085/deleteinstances" - - Result: - 200 - All policy instances deleted. + All policy instances deleted. /deletetypes ~~~~~~~~~~~~ @@ -701,29 +652,27 @@ DELETE DELETE ++++++ - Delete all policy types. +Delete all policy types. - **URL path:** - /deletetypes +**URL path:** + /deletetypes - **Parameters:** +**Parameters:** + None. - None. +**Responses:** + 200: + All policy types deleted. - **Responses:** - - 200: - All policy types deleted. +**Examples:** + **Call**: :: - **Examples:** + curl -X DELETE "http://localhost:8085/deletetypes" - Call: :: + Result: + 200: :: - curl -X DELETE "http://localhost:8085/deletetypes" - - Result: - 200 - All policy types deleted. + All policy types deleted. /policytypes ~~~~~~~~~~~~ @@ -731,31 +680,27 @@ DELETE PUT +++ - Create or update a policy type. - - **URL path:** - /policytypes/{policy-type-id} - - **Parameters:** +Create or update a policy type. - None. +**URL path:** + /policytypes/{policy-type-id} - **Body:** (*Required*) - A JSON object containing the schema for the type. +**Parameters:** + None. - **Responses:** +**Body:** (*Required*) + A JSON object containing the schema for the type. - 200: - The policy type was either created or updated for policy type id: +**Responses:** + 200: + The policy type was either created or updated for policy type id: - **Examples:** +**Examples:** + **Call**: :: - 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 " - { + 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", @@ -825,39 +770,37 @@ PUT "minProperties": 2, "additionalProperties": false, "required": ["scope"] - } - " + }' + + Result: + 200: :: - Result: - 200 - The policy type was either created or updated for policy type id: STD_PolicyModelUnconstrained_0.2.0 + 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:** +Delete a policy type. - None. +**URL path:** + /policytypes/{policy-type-id} - **Responses:** +**Parameters:** + None. - 200: - policy type successfully deleted for policy type id: +**Responses:** + 200: + policy type successfully deleted for policy type id: - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" - curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0" + Result: + 200: :: - Result: - 200 - policy type successfully deleted for policy type id: STD_PolicyModelUnconstrained_0.2.0 + policy type successfully deleted for policy type id: STD_PolicyModelUnconstrained_0.2.0 /{policyId}/{enforceStatus} ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -865,29 +808,27 @@ DELETE PUT +++ - Set a status to a policy instance with an enforceStatus parameter only. +Set a status to a policy instance with an enforceStatus parameter only. - **URL path:** - /{policyId}/{enforceStatus} +**URL path:** + /{policyId}/{enforceStatus} - **Parameters:** +**Parameters:** + None. - None. +**Responses:** + 200: + Status updated for policy: - **Responses:** +**Examples:** + **Call**: :: - 200: - Status updated for policy: + curl -X PUT "http://localhost:8085/Policy1/ENFORCED - **Examples:** + Result: + 200: :: - Call: :: - - curl -X PUT "http://localhost:8085/Policy1/ENFORCED - - Result: - 200 - Status updated for policy: Policy1 + Status updated for policy: Policy1 /{policyId}/{enforceStatus}/{enforceReason} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -895,26 +836,24 @@ PUT PUT ++++ - Send a status to a policy instance with both enforceStatus and enforceReason. - - **URL path:** - /{policyId}/{enforceStatus}/{enforceReason} - - **Parameters:** +Send a status to a policy instance with both enforceStatus and enforceReason. - None. +**URL path:** + /{policyId}/{enforceStatus}/{enforceReason} - **Responses:** +**Parameters:** + None. - 200: - Status updated for policy: +**Responses:** + 200: + Status updated for policy: - **Examples:** +**Examples:** + **Call**: :: - Call: :: + curl -X PUT "http://localhost:8085/Policy1/NOT_ENFORCED/100" - curl -X PUT "http://localhost:8085/Policy1/NOT_ENFORCED/100" + Result: + 200: :: - Result: - 200 - Status updated for policy: Policy1 + Status updated for policy: Policy1 -- 2.16.6