docs/callout-server.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2022 Nordix
   4
   5 .. |nbsp| unicode:: 0xA0
   6    :trim:
   7
   8 .. |nbh| unicode:: 0x2011
   9    :trim:
  10
  11 .. |yaml-icon| image:: ./images/yaml_logo.png
  12                   :width: 40px
  13
  14 =====================
  15 Callout Server
  16 =====================
  17
  18 API Documentation
  19 =================
  20
  21 The O-RAN SC external server is an extension for Near-RealTime RIC simulator. It creates an external web server building RESTful API. It is capable of recieving Rest calls from the northbound simulator version STD_2.0.0 and responses back to it.
  22
  23 The details of API definitions are being explained below:
  24
  25 See `Callout server API <./EXT_SRV_api.html>`_ for full details of the API.
  26
  27 The API is also described in YAML:
  28
  29
  30 .. csv-table::
  31    :header: "API name", "|yaml-icon|"
  32    :widths: 10,5
  33
  34    "Callout Server API", ":download:`link <../near-rt-ric-simulator/test/EXT_SRV/api/EXT_SRV_api.yaml>`"
  35
  36
  37 Admin Functions
  38 ================
  39
  40 Health Check
  41 ------------
  42
  43 GET
  44 +++
  45
  46 Returns the status of the external server.
  47
  48 **URL path:**
  49  /
  50
  51 **Parameters:**
  52   None.
  53
  54 **Responses:**
  55   200:
  56     OK
  57
  58 **Examples:**
  59
  60 **Call**: ::
  61
  62   curl -X GET "http://localhost:9095/"
  63
  64 **Result**:
  65
  66 200: ::
  67
  68   OK
  69
  70
  71 Delete all policy instances in external server
  72 ----------------------------------------------
  73
  74 POST
  75 ++++
  76
  77 Delete all policy instances.
  78
  79 **URL path:**
  80
  81 /serveradmin/deleteinstances
  82
  83 **Parameters:**
  84
  85 None.
  86
  87 **Responses:**
  88
  89 200:
  90
  91 All a1 policy instances deleted
  92
  93 **Examples:**
  94
  95 **Call**: ::
  96
  97   curl -X POST "http://localhost:9095/serveradmin/deleteinstances"
  98
  99 **Result**:
 100
 101 200: ::
 102
 103   All a1 policy instances deleted
 104
 105
 106 Response manipulation
 107 ---------------------
 108 It is possible to manipulate the response of all operations on the external server
 109
 110 POST
 111 ++++
 112
 113 Force a specific response code for the all (the next) external server operation. Unless it is reset, it will always respond the same response code back.
 114
 115 **URL path:**
 116
 117 /serveradmin/forceresponse?code=<http-response-code>
 118
 119 **Parameters:**
 120
 121 code: (*Required*)
 122
 123 The HTTP response code to return.
 124
 125 **Responses:**
 126
 127 200:
 128
 129 Force response code: <expected code>  set for all external server response until it is resetted
 130
 131 **Examples:**
 132
 133 **Call**: ::
 134
 135   curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"
 136
 137 **Result**:
 138
 139 200: ::
 140
 141   Force response code: 500 set for all external server response until it is resetted
 142
 143
 144 Reset response-manipulation
 145 ---------------------------
 146 It is possible to reset the response manipulation on the external server
 147
 148 POST
 149 ++++
 150
 151 Clears specific response code for all (the next) external server operation.
 152
 153 **URL path:**
 154
 155 /serveradmin/forceresponse?code=<http-response-code>
 156
 157 **Parameters:**
 158
 159 code: (*Required*)
 160
 161 The HTTP response code to return.
 162
 163 **Responses:**
 164
 165 200:
 166
 167 Force response code has been resetted for all external server responses
 168
 169 **Examples:**
 170
 171 **Call**: ::
 172
 173   curl -X POST "http://localhost:9095/serveradmin/forceresponse?code=500"
 174
 175 **Result**:
 176
 177 200: ::
 178
 179   Force response code has been resetted for all external server responses
 180
 181
 182 Response time manipulation
 183 --------------------------
 184 It is possible to set a period of time to delay response time.
 185
 186 POST
 187 ++++
 188
 189 Force delayed response of all A1 responses. The setting will remain until the delay is set to '0'
 190
 191 **URL path:**
 192
 193 /serveradmin/forcedelay?delay=<delay-time-seconds>
 194
 195 **Parameters:**
 196
 197 delay: (*Required*)
 198
 199 The time in seconds to delay all responses.
 200
 201 **Responses:**
 202
 203 200:
 204
 205 Force delay: <expected_delay> sec set for all external server responses until it is resetted
 206
 207 **Examples:**
 208
 209 **Call**: ::
 210
 211   curl -X POST "http://localhost:9095/serveradmin/forcedelay?delay=5"
 212
 213 **Result**:
 214
 215 200: ::
 216
 217   Force delay: 5 sec set for all external server responses until it is resetted
 218
 219
 220 Reset response time manipulation
 221 --------------------------------
 222 It is also possible to reset delay response time.
 223
 224 POST
 225 ++++
 226
 227 The setting will clear the delay.
 228
 229 **URL path:**
 230
 231 /serveradmin/forcedelay
 232
 233 **Parameters:**
 234
 235 None.
 236
 237 The time in seconds to delay all responses.
 238
 239 **Responses:**
 240
 241 200:
 242
 243 Force delay has been resetted for all external server responses
 244
 245 **Examples:**
 246
 247 **Call**: ::
 248
 249   curl -X POST "http://localhost:9095/serveradmin/forcedelay"
 250
 251 **Result**:
 252
 253 200: ::
 254
 255   Force delay has been resetted for all external server responses