docs/user-guide-api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 User Guide and APIs
   5 ===================
   6
   7 .. contents::
   8    :depth: 3
   9    :local:
  10
  11 This document explains how to communicate with the A1 Mediator.
  12 Information for maintainers of this platform component is in the Developer Guide.
  13
  14 Example Messages
  15 ----------------
  16
  17 Send the following JSON to create policy type 20008, which supports instances with
  18 a single integer value:
  19
  20 .. code-block:: yaml
  21
  22     {
  23       "name": "tsapolicy",
  24       "description": "tsa parameters",
  25       "policy_type_id": 20008,
  26       "create_schema": {
  27         "$schema": "http://json-schema.org/draft-07/schema#",
  28         "type": "object",
  29         "properties": {
  30           "threshold": {
  31             "type": "integer",
  32             "default": 0
  33           }
  34         },
  35         "additionalProperties": false
  36       }
  37     }
  38
  39
  40 For example, if you put the JSON above into a file called "create.json" you can use
  41 the curl command-line tool to send the request::
  42
  43 .. code::
  44
  45     $ curl -X PUT --header "Content-Type: application/json" --data-raw @create.json "http://localhost/A1-P/v2/policytypes/20008"
  46
  47
  48 Send the following JSON to create an instance of policy type 20008:
  49
  50 .. code-block:: yaml
  51
  52     {
  53       "threshold" : 5
  54     }
  55
  56
  57 For example, you can use the curl command-line tool to send this request::
  58
  59 .. code::
  60
  61     $ curl -X PUT --header "Content-Type: application/json" --data '{"threshold" : 5}' "http://localhost/A1-P/v2/policytypes/20008/policies/tsapolicy145"
  62
  63
  64 Integrating Xapps with A1
  65 -------------------------
  66
  67 The schema for messages sent by A1 to Xapps is labeled ``downstream_message_schema``
  68 in the Southbound API Specification section below. A1 sends policy instance requests
  69 using message type 20010.
  70
  71 The schemas for messages sent by Xapps to A1 appear in the Southbound API
  72 Specification section below. Xapps must use a message type and content appropriate
  73 for the scenario:
  74
  75 #. When an Xapp receives a CREATE message for a policy instance, the Xapp
  76    must respond by sending a message of type 20011 to A1. The content is
  77    defined by schema ``downstream_notification_schema``.  The most convenient
  78    way is to use RMR's return-to-sender (RTS) feature after setting the
  79    message type appropriately.
  80 #. Since policy instances can "deprecate" other instances, there are
  81    times when Xapps need to asynchronously tell A1 that a policy is no
  82    longer active. Use the same message type and schema as above.
  83 #. Xapps can request A1 to re-send all instances of policy type T using a
  84    query, message type 20012.  The schema for that message is defined by
  85    ``policy_query_schema`` (just a body with ``{policy_type_id: ... }``).
  86    When A1 receives this, A1 will send the Xapp a CREATE message N times,
  87    where N is the number of policy instances for type T. The Xapp should reply
  88    normally to each of those as the first item above. That is, after the Xapp
  89    performs the query, the N CREATE messages sent and the N replies
  90    are "as normal".  The query just kicks off this process rather than
  91    an external caller to A1.
  92
  93
  94 Northbound API Specification
  95 ----------------------------
  96
  97 This section shows the Open API specification for the A1 Mediator's
  98 northbound interface, which accepts policy type and policy instance requests.
  99 Following are the api and the response::
 100
 101 #. Healthcheck
 102
 103 .. code::
 104
 105     $ curl -v -X GET "http://localhost/A1-P/v2/healthcheck"
 106
 107 .. code-block:: yaml
 108
 109     < HTTP/1.1 200 OK
 110
 111 #. Get all policy types
 112
 113 .. code::
 114
 115     $ curl -X GET "http://localhost/A1-P/v2/policytypes/"
 116
 117 .. code-block:: yaml
 118
 119     [20001,5003,21001,21000,21002]
 120
 121
 122 #. Get Policy Type based on policyid
 123
 124 .. code::
 125
 126     $ curl -s -X GET "http://localhost/A1-P/v2/policytypes/20001" | jq .
 127
 128 .. code-block:: yaml
 129
 130     {
 131       "create_schema": {
 132         "$schema": "http://json-schema.org/draft-07/schema#",
 133         "properties": {
 134           "additionalProperties": false,
 135           "blocking_rate": {
 136             "default": 10,
 137             "description": "% Connections to block",
 138             "maximum": 1001,
 139             "minimum": 1,
 140             "type": "number"
 141           },
 142           "enforce": {
 143             "default": "true",
 144             "type": "boolean"
 145           },
 146           "window_length": {
 147             "default": 1,
 148             "description": "Sliding window length (in minutes)",
 149             "maximum": 60,
 150             "minimum": 1,
 151             "type": "integer"
 152           }
 153         },
 154         "type": "object"
 155       },
 156       "description": "various parameters to control admission of dual connection",
 157       "name": "admission_control_policy_mine",
 158       "policy_type_id": 20001
 159     }
 160
 161
 162 #. Get all policy instances for a given policy type
 163
 164 .. code::
 165
 166     $ curl -s -X GET "http://localhost/A1-P/v2/policytypes/20001/policies/" | jq .
 167
 168 .. code-block:: yaml
 169
 170     [
 171       "1234",
 172       "1235"
 173     ]
 174
 175 #. Get policy instance for a policy id and policy instance id
 176
 177 .. code::
 178
 179     $ curl -s -X GET "http://localhost/A1-P/v2/policytypes/20001/policies/1234" | jq .
 180
 181 .. code-block:: yaml
 182
 183     {
 184       "blocking_rate": 20,
 185       "enforce": true,
 186       "trigger_threshold": 20,
 187       "window_length": 20
 188     }
 189
 190 #. Create Policy type
 191
 192 .. code::
 193
 194     $ curl -X PUT "http://localhost/A1-P/v2/policytypes/21003/" -H "Content-Type: application/json" -d @policy_schema_ratecontrol.json
 195
 196
 197     $ cat policy_schema_ratecontrol.json
 198
 199 .. code-block:: yaml
 200
 201     {
 202     "name": "Policy for Rate Control",
 203       "policy_type_id":21003,
 204       "description":"This policy is associated with rate control. Entities which support this policy type must accept the following policy inputs (see the payload for more specifics) : class, which represents the class of traffic for which the policy is being enforced",
 205
 206       "create_schema":{
 207           "$schema":"http://json-schema.org/draft-07/schema#",
 208           "type":"object",
 209           "additionalProperties":false,
 210           "required":["class"],
 211           "properties":{
 212               "class":{
 213                   "type":"integer",
 214                   "minimum":1,
 215                   "maximum":256,
 216                   "description":"integer id representing class to which we are applying policy"
 217               },
 218               "enforce":{
 219                   "type":"boolean",
 220                   "description": "Whether to enable or disable enforcement of policy on this class"
 221               },
 222               "window_length":{
 223                   "type":"integer",
 224                   "minimum":15,
 225                   "maximum":300,
 226                   "description":"Sliding window length in seconds"
 227               },
 228               "trigger_threshold":{
 229                   "type":"integer",
 230                   "minimum":1
 231               },
 232               "blocking_rate":{
 233                   "type":"number",
 234                   "minimum":0,
 235                   "maximum":100
 236               }
 237
 238           }
 239       },
 240
 241       "downstream_schema":{
 242           "type":"object",
 243           "additionalProperties":false,
 244           "required":["policy_type_id", "policy_instance_id", "operation"],
 245           "properties":{
 246               "policy_type_id":{
 247                   "type":"integer",
 248                   "enum":[21000]
 249               },
 250               "policy_instance_id":{
 251                   "type":"string"
 252               },
 253               "operation":{
 254                   "type":"string",
 255                   "enum":["CREATE", "UPDATE", "DELETE"]
 256               },
 257               "payload":{
 258                   "$schema":"http://json-schema.org/draft-07/schema#",
 259                   "type":"object",
 260                   "additionalProperties":false,
 261                   "required":["class"],
 262                   "properties":{
 263                       "class":{
 264                           "type":"integer",
 265                           "minimum":1,
 266                           "maximum":256,
 267                           "description":"integer id representing class to which we are applying policy"
 268                       },
 269                       "enforce":{
 270                           "type":"boolean",
 271                           "description": "Whether to enable or disable enforcement of policy on this class"
 272                       },
 273                       "window_length":{
 274                           "type":"integer",
 275                           "minimum":15,
 276                           "maximum":300,
 277                           "description":"Sliding window length in seconds"
 278                       },
 279                       "trigger_threshold":{
 280                           "type":"integer",
 281                           "minimum":1
 282                       },
 283                       "blocking_rate":{
 284                           "type":"number",
 285                           "minimum":0,
 286                           "maximum":100
 287                       }
 288
 289
 290                   }
 291               }
 292           }
 293       },
 294       "notify_schema":{
 295           "type":"object",
 296           "additionalProperties":false,
 297           "required":["policy_type_id", "policy_instance_id", "handler_id", "status"],
 298           "properties":{
 299               "policy_type_id":{
 300                   "type":"integer",
 301                   "enum":[21000]
 302               },
 303               "policy_instance_id":{
 304                   "type":"string"
 305               },
 306               "handler_id":{
 307                   "type":"string"
 308               },
 309               "status":{
 310                   "type":"string",
 311                   "enum":["OK", "ERROR", "DELETED"]
 312               }
 313           }
 314       }
 315     }
 316
 317
 318
 319
 320 #. Create policy instance
 321
 322 .. code::
 323
 324     $ curl -X PUT "http://localhost/A1-P/v2/policytypes/21003/policies/1234" -H "Content-Type: application/json" -d @policy_instance_ratecontrol.json
 325
 326     $ cat policy_instance_ratecontrol.json
 327
 328 .. code-block:: yaml
 329
 330     {
 331         "class":12,
 332         "enforce":true,
 333         "window_length":20,
 334         "blocking_rate":20,
 335         "trigger_threshold":10
 336     }
 337
 338
 339 #. Get policy instance status:
 340
 341 .. code::
 342
 343     $ curl -s -X GET "http://localhost/A1-P/v2/policytypes/21004/policies/1235/status" | jq .
 344
 345 .. code-block:: yaml
 346
 347     {
 348       "created_at": "0001-01-01T00:00:00.000Z",
 349       "instance_status": "IN EFFECT"
 350     }
 351
 352
 353 #. Delete policy type
 354
 355 .. code::
 356
 357     $ curl -s -X DELETE "http://localhost/A1-P/v2/policytypes/21004/"
 358
 359 #. Delete policy instance
 360
 361 .. code::
 362
 363     $ curl -s -X DELETE "http://localhost/A1-P/v2/policytypes/21004/policies/1234/"
 364
 365 #. A1-EI data delivery for a job id:
 366
 367 .. code::
 368
 369     $ curl -X POST "http://localhost/data-delivery" -H "Content-Type: application/json" -d @a1eidata.json
 370
 371     $ cat a1eidata.json
 372
 373 .. code-block:: yaml
 374
 375     {
 376     "job":"100",
 377     "payload":"payload"
 378     }
 379
 380
 381
 382 Southbound API Specification
 383 ----------------------------
 384
 385 This section shows Open API schemas for the A1 Mediator's southbound interface,
 386 which communicates with Xapps via RMR. A1 sends policy instance requests using
 387 message type 20010. Xapps may send requests to A1 using message types 20011 and
 388 20012.
 389
 390
 391 .. literalinclude:: a1_xapp_contract_openapi.yaml
 392    :language: yaml
 393    :linenos: