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