docs/simulator-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 .. Copyright (C) 2020 Nordix
   4
   5 .. _simulator-api:
   6
   7 =============
   8 Simulator API
   9 =============
  10
  11 This document describes the API used to manage policy types and manipulate the simulator.
  12
  13 The simulator supports different versions of the A1 interface. Some functions are common for all version, and some are
  14 specific for a certain version.
  15
  16 Common Functions
  17 ================
  18
  19 Health Check
  20 ------------
  21
  22 The status of the simulator.
  23
  24 /
  25 ~~
  26
  27 GET
  28 +++
  29
  30 Returns the status of the simulator.
  31
  32 **URL path:**
  33   /
  34
  35 **Parameters:**
  36   None.
  37
  38 **Responses:**
  39   200:
  40     Simulator is living.
  41
  42 **Examples:**
  43   **Call**: ::
  44
  45     curl -X GET "http://localhost:8085/"
  46
  47   Result:
  48     200: ::
  49
  50       Simulator is living (OSC_2.1.0 responds OK)
  51
  52 Supported Interfaces
  53 --------------------
  54
  55 The simulator can support different versions of the A1 interface. With this API the supported versions can be listed.
  56
  57 /container_interfaces
  58 ~~~~~~~~~~~~~~~~~~~~~
  59
  60 GET
  61 +++
  62
  63 Returns the status of the simulator. (Not available for A1 Standard 1.1.3)
  64
  65 **URL path:**
  66   /container_interfaces
  67
  68 **Parameters:**
  69   None.
  70
  71 **Responses:**
  72   200:
  73     List of supported interfaces.
  74
  75 **Examples:**
  76   **Call**: ::
  77
  78     curl -X GET "http://localhost:8085/container_interfaces"
  79
  80   Result:
  81     200: ::
  82
  83       1.1.x-alpha.2 OSC_2.1.0 STD_1.1.3
  84
  85 Counters
  86 --------
  87
  88 The simulator keeps counts of different things that can be accessed.
  89
  90 /counter
  91 ~~~~~~~~
  92
  93 GET
  94 +++
  95
  96 Get a counter. Counter-name can be one of the following: 'num_instances', 'num_types' or 'interface'.
  97
  98 **URL path:**
  99   /counter/{counter-name}
 100
 101 **Parameters:**
 102   None.
 103
 104 **Responses:**
 105   200:
 106     The counter value for the given counter.
 107
 108 **Examples:**
 109   **Call**: ::
 110
 111     curl -X GET "http://localhost:8085/counter/num_instances"
 112
 113   Result:
 114     200: ::
 115
 116       10
 117
 118 Version Specific Functions
 119 ==========================
 120
 121 The methods available to control the simulator depends on the version of the A1 API the simulator is simulating.
 122
 123 OSC_2.1.0
 124 ---------
 125
 126 This section describes the available administrative functions for the OSC_2.1.0 version of A1.
 127
 128 To see the A1 functions for this version, see `OSC_2.1.0 API`_.
 129
 130 .. _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
 131
 132 /deleteinstances
 133 ~~~~~~~~~~~~~~~~
 134
 135 POST
 136 ++++
 137
 138 Delete all policy instances.
 139
 140 **URL path:**
 141   /deleteinstances
 142
 143 **Parameters:**
 144   None.
 145
 146 **Responses:**
 147   200:
 148     All policy instances deleted.
 149
 150 **Examples:**
 151   **Call**: ::
 152
 153     curl -X POST "http://localhost:8085/deleteinstances"
 154
 155   Result:
 156     200: ::
 157
 158       All policy instances deleted.
 159
 160 /deleteall
 161 ~~~~~~~~~~~~~~~~
 162
 163 POST
 164 ++++
 165
 166 Full reset.
 167
 168 **URL path:**
 169   /deleteall
 170
 171 **Parameters:**
 172   None.
 173
 174 **Responses:**
 175   200:
 176     All policy instances and types deleted.
 177
 178 **Examples:**
 179   **Call**: ::
 180
 181     curl -X POST "http://localhost:8085/deleteall"
 182
 183   Result:
 184     200: ::
 185
 186       All policy instances and types deleted.
 187
 188 /policytype
 189 ~~~~~~~~~~~
 190
 191 PUT
 192 +++
 193
 194 Create a policy type.
 195
 196 **URL path:**
 197   /policytype?id=<policy-type-id>
 198
 199 **Parameters:**
 200   id: (*Required*)
 201     The ID of the policy type.
 202
 203 **Body:** (*Required*)
 204     A JSON object containing the schema for the type.
 205
 206 **Responses:**
 207   200:
 208     Policy type <policy-type-id> is OK.
 209   201:
 210     Policy type <policy-type-id> is OK.
 211
 212 **Examples:**
 213   **Call**: ::
 214
 215     curl -X PUT "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 216       -H  "Content-Type: application/json"
 217       -d '{
 218             "$schema": "http://json-schema.org/draft-07/schema#",
 219             "title": "STD_PolicyModelUnconstrained_0.2.0",
 220             "description": "Standard model of a policy with unconstrained scope id combinations",
 221             "type": "object",
 222             "properties": {
 223               "scope": {
 224                 "type": "object",
 225                 "properties": {
 226                   "ueId": {"type": "string"},
 227                   "groupId": {"type": "string"},
 228                   "sliceId": {"type": "string"},
 229                   "qosId": {"type": "string"},
 230                   "cellId": {"type": "string"}
 231                 },
 232                 "minProperties": 1,
 233                 "additionalProperties": false
 234               },
 235               "qosObjectives": {
 236                 "type": "object",
 237                 "properties": {
 238                   "gfbr": {"type": "number"},
 239                   "mfbr": {"type": "number"},
 240                   "priorityLevel": {"type": "number"},
 241                   "pdb": {"type": "number"}
 242                 },
 243                 "additionalProperties": false
 244               },
 245               "qoeObjectives": {
 246                 "type": "object",
 247                 "properties": {
 248                   "qoeScore": {"type": "number"},
 249                   "initialBuffering": {"type": "number"},
 250                   "reBuffFreq": {"type": "number"},
 251                   "stallRatio": {"type": "number"}
 252                 },
 253                 "additionalProperties": false
 254               },
 255               "resources": {
 256                 "type": "array",
 257                 "items": {
 258                   "type": "object",
 259                   "properties": {
 260                     "cellIdList": {
 261                       "type": "array",
 262                       "minItems": 1,
 263                       "uniqueItems": true,
 264                       "items": {
 265                         "type": "string"
 266                       }
 267                     },
 268                     "preference": {
 269                       "type": "string",
 270                       "enum": [
 271                         "SHALL",
 272                         "PREFER",
 273                         "AVOID",
 274                         "FORBID"
 275                       ]
 276                     },
 277                     "primary": {"type": "boolean"}
 278                   },
 279                   "additionalProperties": false,
 280                   "required": ["cellIdList", "preference"]
 281                 }
 282               }
 283             },
 284             "minProperties": 2,
 285             "additionalProperties": false,
 286             "required": ["scope"]
 287           }'
 288
 289   Result:
 290     201: ::
 291
 292       Policy type STD_PolicyModelUnconstrained_0.2.0 is OK
 293
 294 DELETE
 295 ++++++
 296
 297 Delete a policy type.
 298
 299 **URL path:**
 300   /policytype?id=<policy-type-id>
 301
 302 **Parameters:**
 303   id: (*Required*)
 304     The ID of the policy type.
 305
 306 **Responses:**
 307   204:
 308     Policy type <policy-type-id> is OK.
 309
 310 **Examples:**
 311   **Call**: ::
 312
 313    curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 314
 315   Result:
 316     204: ::
 317
 318       Policy type STD_PolicyModelUnconstrained_0.2.0 is OK
 319
 320 /policytypes
 321 ~~~~~~~~~~~~
 322
 323 GET
 324 +++
 325
 326 Get a list of policy types.
 327
 328 **URL path:**
 329   /policytypes
 330
 331 **Parameters:**
 332   None.
 333
 334 **Responses:**
 335   200:
 336     A list of policy types.
 337
 338 **Examples:**
 339   **Call**: ::
 340
 341     curl -X GET "http://localhost:8085/policytypes"
 342
 343   Result:
 344     200: ::
 345
 346       STD_PolicyModelUnconstrained_0.2.0
 347
 348 /forceresponse
 349 ~~~~~~~~~~~~~~
 350
 351 POST
 352 ++++
 353
 354 Force a specific response code for an A1 operation.
 355
 356 **URL path:**
 357   /forceresponse?responsecode=<http-response-code>
 358
 359 **Parameters:**
 360   responsecode: (*Required*)
 361     The HTTP response code to return.
 362
 363 **Responses:**
 364   200:
 365     Force response code:  <expected code> set for one single A1 response
 366
 367 **Examples:**
 368   **Call**: ::
 369
 370     curl -X POST "http://localhost:8085/forceresponse?responsecode=400"
 371
 372   Result:
 373     200: ::
 374
 375       Force response code:  400 set for one single A1 response
 376
 377 /forcedelay
 378 ~~~~~~~~~~~
 379
 380 POST
 381 ++++
 382
 383 Force delayed response of all A1 operations.
 384
 385 **URL path:**
 386   /forcedelay?delay=<delay-time-seconds>
 387
 388 **Parameters:**
 389   delay: (*Required*)
 390     The time in seconds to delay all responses.
 391
 392 **Responses:**
 393   200:
 394     Force delay: <expected delay> sec set for all A1 responses
 395
 396 **Examples:**
 397   **Call**: ::
 398
 399     curl -X POST "http://localhost:8085/forcedelay?delay=2"
 400
 401   Result:
 402     200: ::
 403
 404       Force delay: 2 sec set for all A1 responses
 405
 406 /status
 407 ~~~~~~~
 408
 409 PUT
 410 +++
 411
 412 Set status and optional reason, delete and time stamp.
 413
 414 **URL path:**
 415   /status?policyid=<policyid>&status=<status>&deleted=<value>&created_at=<time-stamp>
 416
 417 **Parameters:**
 418   policyid: (*Required*)
 419     The ID of a policy.
 420   status: (*Required*)
 421     The status of a policy.
 422   deleted: (*Optional*)
 423     True or false for real values, but accepts anything for error testing.
 424   created_at: (*Optional*)
 425     Time stamp for the status.
 426
 427 **Responses:**
 428   200:
 429     Status set to <status> for policy <policy-id>
 430
 431 **Examples:**
 432   **Call**: ::
 433
 434     curl -X PUT "http://localhost:8085/policyid=Policy1&status?status=Accepted
 435
 436   Result:
 437     200: ::
 438
 439       Status set to Accepted for policy Policy1.
 440
 441 A1 Standard 1.1.3
 442 -----------------
 443
 444 This section describes the available administrative functions for the A1 Standard 1.1.3 version of A1.
 445
 446 To see the A1 functions for this version, see `A1 Standard 1.1.3 API`_.
 447
 448 .. _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
 449
 450 /deleteinstances
 451 ~~~~~~~~~~~~~~~~
 452
 453 POST
 454 ++++
 455
 456 Delete all policy instances.
 457
 458 **URL path:**
 459   /deleteinstances
 460
 461 **Parameters:**
 462   None.
 463
 464 **Responses:**
 465   200:
 466     All policy instances deleted.
 467
 468 **Examples:**
 469   **Call**: ::
 470
 471     curl -X POST "http://localhost:8085/deleteinstances"
 472
 473   Result:
 474     200: ::
 475
 476       All policy instances deleted.
 477
 478 /deleteall
 479 ~~~~~~~~~~
 480
 481 POST
 482 ++++
 483
 484 Full reset.
 485
 486 **URL path:**
 487   /deleteinstances
 488
 489 **Parameters:**
 490   None.
 491
 492 **Responses:**
 493   200:
 494     All policy instances deleted.
 495
 496 **Examples:**
 497   **Call**: ::
 498
 499     curl -X POST "http://localhost:8085/deleteall"
 500
 501   Result:
 502     200: ::
 503
 504       All policy instances deleted.
 505
 506 /forceresponse
 507 ~~~~~~~~~~~~~~
 508
 509 POST
 510 ++++
 511
 512 Force a specific response code for an A1 operation.
 513
 514 **URL path:**
 515   /forceresponse?responsecode=<http-response-code>
 516
 517 **Parameters:**
 518   responsecode: (*Required*)
 519     The HTTP response code to return.
 520
 521 **Responses:**
 522   200:
 523     Force response code: <expected code> set for one single A1 response
 524
 525 **Examples:**
 526   **Call**: ::
 527
 528     curl -X POST "http://localhost:8085/forceresponse?responsecode=400"
 529
 530   Result:
 531     200: ::
 532
 533       Force response code: 400 set for one single A1 response
 534
 535 /forcedelay
 536 ~~~~~~~~~~~
 537
 538 POST
 539 ++++
 540
 541 Force delayed response of all A1 operations.
 542
 543 **URL path:**
 544   /forcedelay?delay=<delay-time-seconds>
 545
 546 **Parameters:**
 547   delay: (*Required*)
 548     The time in seconds to delay all responses.
 549
 550 **Responses:**
 551   200:
 552     Force delay: <expected delay> sec set for all A1 responses
 553
 554 **Examples:**
 555   **Call**: ::
 556
 557     curl -X POST "http://localhost:8085/forcedelay?delay=2"
 558
 559   Result:
 560     200: ::
 561
 562       Force delay: 2 sec set for all A1 responses
 563
 564 /status
 565 ~~~~~~~
 566
 567 PUT
 568 +++
 569
 570 Set status and optional reason, delete and time stamp.
 571
 572 **URL path:**
 573   /status?policyid=<policyid>&status=<status>&reason=<reason>
 574
 575 **Parameters:**
 576   policyid: (*Required*)
 577     The ID of a policy.
 578   status: (*Required*)
 579     The status of a policy.
 580   reason: (*Optional*)
 581     The reason for the status.
 582
 583 **Responses:**
 584   200:
 585     Status set to <status> for policy <policy-id>
 586
 587 **Examples:**
 588   **Call**: ::
 589
 590     curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted
 591
 592   Result:
 593     200: ::
 594
 595       Status set to Accepted for policy Policy1
 596
 597 /sendstatus
 598 ~~~~~~~~~~~
 599
 600 POST
 601 ++++
 602
 603 Send status for policy.
 604
 605 **URL path:**
 606   /sendstatus?policyid=<policy-id>
 607
 608 **Parameters:**
 609   policyid: (*Required*)
 610     The ID of the policy to send status for.
 611
 612 **Responses:**
 613   200:
 614     Is a JSON with the response of the actual post request to the callback server, whatever that is.
 615
 616 **Examples:**
 617   **Call**: ::
 618
 619     curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2"
 620
 621   Result:
 622     200
 623
 624 1.1.x-alpha.2
 625 -------------
 626
 627 This section describes the available administrative functions for the 1.1.x-alpha.2 version of A1.
 628
 629 To see the A1 functions for this version, see `1.1.x-alpha.2 API`_.
 630
 631 .. _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
 632
 633 /deleteinstances
 634 ~~~~~~~~~~~~~~~~
 635
 636 DELETE
 637 ++++++
 638
 639 Delete all policy instances.
 640
 641 **URL path:**
 642   /deleteinstances
 643
 644 **Parameters:**
 645   None.
 646
 647 **Responses:**
 648   200:
 649     All policy instances deleted.
 650
 651 **Examples:**
 652   **Call**: ::
 653
 654     curl -X DELETE "http://localhost:8085/deleteinstances"
 655
 656   Result:
 657     200: ::
 658
 659       All policy instances deleted.
 660
 661 /deletetypes
 662 ~~~~~~~~~~~~
 663
 664 DELETE
 665 ++++++
 666
 667 Delete all policy types.
 668
 669 **URL path:**
 670   /deletetypes
 671
 672 **Parameters:**
 673   None.
 674
 675 **Responses:**
 676   200:
 677     All policy types deleted.
 678
 679 **Examples:**
 680   **Call**: ::
 681
 682     curl -X DELETE "http://localhost:8085/deletetypes"
 683
 684   Result:
 685     200: ::
 686
 687       All policy types deleted.
 688
 689 /policytypes
 690 ~~~~~~~~~~~~
 691
 692 PUT
 693 +++
 694
 695 Create or update a policy type.
 696
 697 **URL path:**
 698   /policytypes/{policy-type-id}
 699
 700 **Parameters:**
 701   None.
 702
 703 **Body:** (*Required*)
 704     A JSON object containing the schema for the type.
 705
 706 **Responses:**
 707   200:
 708     The policy type was either created or updated for policy type id: <policy-type-id>
 709
 710 **Examples:**
 711   **Call**: ::
 712
 713     curl -X PUT "http://localhost:8085/policytype/Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 714       -H  "Content-Type: application/json"
 715       -d '{
 716             "$schema": "http://json-schema.org/draft-07/schema#",
 717             "title": "STD_PolicyModelUnconstrained_0.2.0",
 718             "description": "Standard model of a policy with unconstrained scope id combinations",
 719             "type": "object",
 720             "properties": {
 721               "scope": {
 722                 "type": "object",
 723                 "properties": {
 724                   "ueId": {"type": "string"},
 725                   "groupId": {"type": "string"},
 726                   "sliceId": {"type": "string"},
 727                   "qosId": {"type": "string"},
 728                   "cellId": {"type": "string"}
 729                 },
 730                 "minProperties": 1,
 731                 "additionalProperties": false
 732               },
 733               "qosObjectives": {
 734                 "type": "object",
 735                 "properties": {
 736                   "gfbr": {"type": "number"},
 737                   "mfbr": {"type": "number"},
 738                   "priorityLevel": {"type": "number"},
 739                   "pdb": {"type": "number"}
 740                 },
 741                 "additionalProperties": false
 742               },
 743               "qoeObjectives": {
 744                 "type": "object",
 745                 "properties": {
 746                   "qoeScore": {"type": "number"},
 747                   "initialBuffering": {"type": "number"},
 748                   "reBuffFreq": {"type": "number"},
 749                   "stallRatio": {"type": "number"}
 750                 },
 751                 "additionalProperties": false
 752               },
 753               "resources": {
 754                 "type": "array",
 755                 "items": {
 756                   "type": "object",
 757                   "properties": {
 758                     "cellIdList": {
 759                       "type": "array",
 760                       "minItems": 1,
 761                       "uniqueItems": true,
 762                       "items": {
 763                         "type": "string"
 764                       }
 765                     },
 766                     "preference": {
 767                       "type": "string",
 768                       "enum": [
 769                         "SHALL",
 770                         "PREFER",
 771                         "AVOID",
 772                         "FORBID"
 773                       ]
 774                     },
 775                     "primary": {"type": "boolean"}
 776                   },
 777                   "additionalProperties": false,
 778                   "required": ["cellIdList", "preference"]
 779                 }
 780               }
 781             },
 782             "minProperties": 2,
 783             "additionalProperties": false,
 784             "required": ["scope"]
 785           }'
 786
 787   Result:
 788     200: ::
 789
 790       The policy type was either created or updated for policy type id: STD_PolicyModelUnconstrained_0.2.0
 791
 792 DELETE
 793 ++++++
 794
 795 Delete a policy type.
 796
 797 **URL path:**
 798   /policytypes/{policy-type-id}
 799
 800 **Parameters:**
 801   None.
 802
 803 **Responses:**
 804   200:
 805     policy type successfully deleted for policy type id: <policy-type-id>
 806
 807 **Examples:**
 808   **Call**: ::
 809
 810    curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 811
 812   Result:
 813     200: ::
 814
 815       policy type successfully deleted for policy type id: STD_PolicyModelUnconstrained_0.2.0
 816
 817 /{policyId}/{enforceStatus}
 818 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 819
 820 PUT
 821 +++
 822
 823 Set a status to a policy instance with an enforceStatus parameter only.
 824
 825 **URL path:**
 826   /{policyId}/{enforceStatus}
 827
 828 **Parameters:**
 829   None.
 830
 831 **Responses:**
 832   200:
 833     Status updated for policy: <policyId>
 834
 835 **Examples:**
 836   **Call**: ::
 837
 838     curl -X PUT "http://localhost:8085/Policy1/ENFORCED
 839
 840   Result:
 841     200: ::
 842
 843       Status updated for policy: Policy1
 844
 845 /{policyId}/{enforceStatus}/{enforceReason}
 846 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 847
 848 PUT
 849 ++++
 850
 851 Send a status to a policy instance with both enforceStatus and enforceReason.
 852
 853 **URL path:**
 854   /{policyId}/{enforceStatus}/{enforceReason}
 855
 856 **Parameters:**
 857   None.
 858
 859 **Responses:**
 860   200:
 861     Status updated for policy: <policyId>
 862
 863 **Examples:**
 864   **Call**: ::
 865
 866     curl -X PUT "http://localhost:8085/Policy1/NOT_ENFORCED/100"
 867
 868   Result:
 869     200: ::
 870
 871       Status updated for policy: Policy1