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 .. _calloutserver:
  15
  16 =====================
  17 Callout Server
  18 =====================
  19
  20 API Documentation
  21 =================
  22
  23 The O-RAN SC external call-out server allows behavioral extensions to be added to the A1 Simulator. It creates an external call-out server, which provides a RESTful API. A1 Policy operations, for some A1 Policy Types, can then be redirected to the external call-out server, supporting supplemental simulator behavior for those A1 Policy Types.
  24
  25 **Note:** call-out server functionality is only available for *'STD_2.0.0'* version simulators.
  26
  27 The external call-out server exposes a 'Callout server API' REST API. This internal API is invoked directly by the A1 Simulator, and is not intended to be used by any other client.  The 'Callout Server API' is documented in `Callout Server API <./EXT_SRV_api.html>`_ and in OpenAPI YAML format:
  28
  29 .. csv-table::
  30    :header: "API name", "|yaml-icon|"
  31    :widths: 10,5
  32
  33    "Callout Server API", ":download:`link <../near-rt-ric-simulator/test/EXT_SRV/api/EXT_SRV_api.yaml>`"
  34
  35 External call-out servers also expose an 'Admin API' to manipulate the behavior of the call-out server itself. The 'Callout Server Admin API' is documented below:
  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