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
  44 **Call**: ::
  45
  46   curl -X GET "http://localhost:8085/"
  47
  48 **Result**:
  49
  50 200: ::
  51
  52   Simulator is living (OSC_2.1.0 responds 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   1.1.x-alpha.2 OSC_2.1.0 STD_1.1.3
  92
  93 Counters
  94 --------
  95
  96 The simulator keeps counts 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' or 'interface'.
 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 Version Specific Functions
 133 ==========================
 134
 135 The methods available to control the simulator depends on the version of the A1 API the simulator is simulating.
 136
 137 OSC_2.1.0
 138 ---------
 139
 140 This section describes the available administrative functions for the OSC_2.1.0 version of A1.
 141
 142 To see the A1 functions for this version, see `OSC_2.1.0 API`_.
 143
 144 .. _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
 145
 146 /deleteinstances
 147 ~~~~~~~~~~~~~~~~
 148
 149 POST
 150 ++++
 151
 152 Delete all policy instances.
 153
 154 **URL path:**
 155
 156 /deleteinstances
 157
 158 **Parameters:**
 159
 160 None.
 161
 162 **Responses:**
 163
 164 200:
 165
 166 All policy instances deleted.
 167
 168 **Examples:**
 169
 170 **Call**: ::
 171
 172   curl -X POST "http://localhost:8085/deleteinstances"
 173
 174 **Result**:
 175
 176 200: ::
 177
 178   All policy instances deleted.
 179
 180 /deleteall
 181 ~~~~~~~~~~~~~~~~
 182
 183 POST
 184 ++++
 185
 186 Full reset.
 187
 188 **URL path:**
 189
 190 /deleteall
 191
 192 **Parameters:**
 193
 194 None.
 195
 196 **Responses:**
 197
 198 200:
 199
 200 All policy instances and types deleted.
 201
 202 **Examples:**
 203
 204  **Call**: ::
 205
 206   curl -X POST "http://localhost:8085/deleteall"
 207
 208 **Result**:
 209
 210 200: ::
 211
 212   All policy instances and types deleted.
 213
 214 /policytype
 215 ~~~~~~~~~~~
 216
 217 PUT
 218 +++
 219
 220 Create a policy type.
 221
 222 **URL path:**
 223
 224 /policytype?id=<policy-type-id>
 225
 226 **Parameters:**
 227
 228 id: (*Required*)
 229
 230 The ID of the policy type.
 231
 232 **Body:** (*Required*)
 233
 234 A JSON object containing the schema for the type.
 235
 236 **Responses:**
 237
 238 200:
 239
 240 Policy type <policy-type-id> is OK.
 241
 242 201:
 243
 244 Policy type <policy-type-id> is OK.
 245
 246 **Examples:**
 247
 248 **Call**: ::
 249
 250   curl -X PUT "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 251     -H  "Content-Type: application/json"
 252     -d '{
 253           "$schema": "http://json-schema.org/draft-07/schema#",
 254           "title": "STD_PolicyModelUnconstrained_0.2.0",
 255           "description": "Standard model of a policy with unconstrained scope id combinations",
 256           "type": "object",
 257           "properties": {
 258             "scope": {
 259               "type": "object",
 260               "properties": {
 261                 "ueId": {"type": "string"},
 262                 "groupId": {"type": "string"},
 263                 "sliceId": {"type": "string"},
 264                 "qosId": {"type": "string"},
 265                 "cellId": {"type": "string"}
 266               },
 267               "minProperties": 1,
 268               "additionalProperties": false
 269             },
 270             "qosObjectives": {
 271               "type": "object",
 272               "properties": {
 273                 "gfbr": {"type": "number"},
 274                 "mfbr": {"type": "number"},
 275                 "priorityLevel": {"type": "number"},
 276                 "pdb": {"type": "number"}
 277               },
 278               "additionalProperties": false
 279             },
 280             "qoeObjectives": {
 281               "type": "object",
 282               "properties": {
 283                 "qoeScore": {"type": "number"},
 284                 "initialBuffering": {"type": "number"},
 285                 "reBuffFreq": {"type": "number"},
 286                 "stallRatio": {"type": "number"}
 287               },
 288               "additionalProperties": false
 289             },
 290             "resources": {
 291               "type": "array",
 292               "items": {
 293                 "type": "object",
 294                 "properties": {
 295                   "cellIdList": {
 296                     "type": "array",
 297                     "minItems": 1,
 298                     "uniqueItems": true,
 299                     "items": {
 300                       "type": "string"
 301                     }
 302                   },
 303                   "preference": {
 304                     "type": "string",
 305                     "enum": [
 306                       "SHALL",
 307                       "PREFER",
 308                       "AVOID",
 309                       "FORBID"
 310                     ]
 311                   },
 312                   "primary": {"type": "boolean"}
 313                 },
 314                 "additionalProperties": false,
 315                 "required": ["cellIdList", "preference"]
 316               }
 317             }
 318           },
 319           "minProperties": 2,
 320           "additionalProperties": false,
 321           "required": ["scope"]
 322         }'
 323
 324 **Result**:
 325
 326 201: ::
 327
 328   Policy type STD_PolicyModelUnconstrained_0.2.0 is OK
 329
 330 DELETE
 331 ++++++
 332
 333 Delete a policy type.
 334
 335 **URL path:**
 336
 337 /policytype?id=<policy-type-id>
 338
 339 **Parameters:**
 340
 341 id: (*Required*)
 342
 343 The ID of the policy type.
 344
 345 **Responses:**
 346
 347 204:
 348
 349 Policy type <policy-type-id> is OK.
 350
 351 **Examples:**
 352
 353 **Call**: ::
 354
 355   curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 356
 357 **Result**:
 358
 359 204: ::
 360
 361   Policy type STD_PolicyModelUnconstrained_0.2.0 is OK
 362
 363 /policytypes
 364 ~~~~~~~~~~~~
 365
 366 GET
 367 +++
 368
 369 Get a list of policy types.
 370
 371 **URL path:**
 372
 373 /policytypes
 374
 375 **Parameters:**
 376
 377 None.
 378
 379 **Responses:**
 380
 381 200:
 382
 383 A list of policy types.
 384
 385 **Examples:**
 386
 387 **Call**: ::
 388
 389   curl -X GET "http://localhost:8085/policytypes"
 390
 391 **Result**:
 392
 393 200: ::
 394
 395   STD_PolicyModelUnconstrained_0.2.0
 396
 397 /forceresponse
 398 ~~~~~~~~~~~~~~
 399
 400 POST
 401 ++++
 402
 403 Force a specific response code for an A1 operation.
 404
 405 **URL path:**
 406
 407 /forceresponse?responsecode=<http-response-code>
 408
 409 **Parameters:**
 410
 411 responsecode: (*Required*)
 412
 413 The HTTP response code to return.
 414
 415 **Responses:**
 416
 417 200:
 418
 419 Force response code:  <expected code> set for one single A1 response
 420
 421 **Examples:**
 422
 423 **Call**: ::
 424
 425   curl -X POST "http://localhost:8085/forceresponse?responsecode=400"
 426
 427 **Result**:
 428
 429 200: ::
 430
 431   Force response code:  400 set for one single A1 response
 432
 433 /forcedelay
 434 ~~~~~~~~~~~
 435
 436 POST
 437 ++++
 438
 439 Force delayed response of all A1 operations.
 440
 441 **URL path:**
 442
 443 /forcedelay?delay=<delay-time-seconds>
 444
 445 **Parameters:**
 446
 447 delay: (*Required*)
 448
 449 The time in seconds to delay all responses.
 450
 451 **Responses:**
 452
 453 200:
 454
 455 Force delay: <expected delay> sec set for all A1 responses
 456
 457 **Examples:**
 458
 459 **Call**: ::
 460
 461   curl -X POST "http://localhost:8085/forcedelay?delay=2"
 462
 463 **Result**:
 464
 465 200: ::
 466
 467   Force delay: 2 sec set for all A1 responses
 468
 469 /status
 470 ~~~~~~~
 471
 472 PUT
 473 +++
 474
 475 Set status and optional reason, delete and time stamp.
 476
 477 **URL path:**
 478
 479 /status?policyid=<policyid>&status=<status>&deleted=<value>&created_at=<time-stamp>
 480
 481 **Parameters:**
 482
 483 policyid: (*Required*)
 484
 485 The ID of a policy.
 486
 487 status: (*Required*)
 488
 489 The status of a policy.
 490
 491 deleted: (*Optional*)
 492
 493 True or false for real values, but accepts anything for error testing.
 494
 495 created_at: (*Optional*)
 496
 497 Time stamp for the status.
 498
 499 **Responses:**
 500
 501 200:
 502
 503 Status set to <status> for policy <policy-id>
 504
 505 **Examples:**
 506
 507 **Call**: ::
 508
 509   curl -X PUT "http://localhost:8085/policyid=Policy1&status?status=Accepted
 510
 511 **Result**:
 512
 513 200: ::
 514
 515   Status set to Accepted for policy Policy1.
 516
 517 A1 Standard 1.1.3
 518 -----------------
 519
 520 This section describes the available administrative functions for the A1 Standard 1.1.3 version of A1.
 521
 522 To see the A1 functions for this version, see `A1 Standard 1.1.3 API`_.
 523
 524 .. _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
 525
 526 /deleteinstances
 527 ~~~~~~~~~~~~~~~~
 528
 529 POST
 530 ++++
 531
 532 Delete all policy instances.
 533
 534 **URL path:**
 535
 536 /deleteinstances
 537
 538 **Parameters:**
 539
 540 None.
 541
 542 **Responses:**
 543
 544 200:
 545
 546 All policy instances deleted.
 547
 548 **Examples:**
 549
 550 **Call**: ::
 551
 552   curl -X POST "http://localhost:8085/deleteinstances"
 553
 554 **Result**:
 555
 556 200: ::
 557
 558   All policy instances deleted.
 559
 560 /deleteall
 561 ~~~~~~~~~~
 562
 563 POST
 564 ++++
 565
 566 Full reset.
 567
 568 **URL path:**
 569
 570 /deleteinstances
 571
 572 **Parameters:**
 573
 574 None.
 575
 576 **Responses:**
 577
 578 200:
 579
 580 All policy instances deleted.
 581
 582 **Examples:**
 583
 584 **Call**: ::
 585
 586   curl -X POST "http://localhost:8085/deleteall"
 587
 588 **Result**:
 589
 590 200: ::
 591
 592   All policy instances deleted.
 593
 594 /forceresponse
 595 ~~~~~~~~~~~~~~
 596
 597 POST
 598 ++++
 599
 600 Force a specific response code for an A1 operation.
 601
 602 **URL path:**
 603
 604 /forceresponse?responsecode=<http-response-code>
 605
 606 **Parameters:**
 607
 608 responsecode: (*Required*)
 609
 610 The HTTP response code to return.
 611
 612 **Responses:**
 613
 614 200:
 615
 616 Force response code: <expected code> set for one single A1 response
 617
 618 **Examples:**
 619
 620 **Call**: ::
 621
 622   curl -X POST "http://localhost:8085/forceresponse?responsecode=400"
 623
 624 **Result**:
 625
 626 200: ::
 627
 628   Force response code: 400 set for one single A1 response
 629
 630 /forcedelay
 631 ~~~~~~~~~~~
 632
 633 POST
 634 ++++
 635
 636 Force delayed response of all A1 operations.
 637
 638 **URL path:**
 639
 640 /forcedelay?delay=<delay-time-seconds>
 641
 642 **Parameters:**
 643
 644 delay: (*Required*)
 645
 646 The time in seconds to delay all responses.
 647
 648 **Responses:**
 649
 650 200:
 651
 652 Force delay: <expected delay> sec set for all A1 responses
 653
 654 **Examples:**
 655
 656 **Call**: ::
 657
 658   curl -X POST "http://localhost:8085/forcedelay?delay=2"
 659
 660 **Result**:
 661
 662 200: ::
 663
 664   Force delay: 2 sec set for all A1 responses
 665
 666 /status
 667 ~~~~~~~
 668
 669 PUT
 670 +++
 671
 672 Set status and optional reason, delete and time stamp.
 673
 674 **URL path:**
 675
 676 /status?policyid=<policyid>&status=<status>&reason=<reason>
 677
 678 **Parameters:**
 679
 680 policyid: (*Required*)
 681
 682 The ID of a policy.
 683
 684 status: (*Required*)
 685
 686 The status of a policy.
 687
 688 reason: (*Optional*)
 689
 690 The reason for the status.
 691
 692 **Responses:**
 693
 694 200:
 695
 696 Status set to <status> for policy <policy-id>
 697
 698 **Examples:**
 699
 700 **Call**: ::
 701
 702   curl -X PUT "http://localhost:8085/status?policyid=Policy1&status=Accepted
 703
 704 **Result**:
 705
 706 200: ::
 707
 708   Status set to Accepted for policy Policy1
 709
 710 /sendstatus
 711 ~~~~~~~~~~~
 712
 713 POST
 714 ++++
 715
 716 Send status for policy.
 717
 718 **URL path:**
 719
 720 /sendstatus?policyid=<policy-id>
 721
 722 **Parameters:**
 723
 724 policyid: (*Required*)
 725
 726 The ID of the policy to send status for.
 727
 728 **Responses:**
 729
 730 200:
 731
 732 Is a JSON with the response of the actual post request to the callback server, whatever that is.
 733
 734 **Examples:**
 735
 736 **Call**: ::
 737
 738   curl -X POST "http://localhost:8085/sendstatus?policyid=Policy2"
 739
 740 **Result**:
 741
 742 200
 743
 744 1.1.x-alpha.2
 745 -------------
 746
 747 This section describes the available administrative functions for the 1.1.x-alpha.2 version of A1.
 748
 749 To see the A1 functions for this version, see `1.1.x-alpha.2 API`_.
 750
 751 .. _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
 752
 753 /deleteinstances
 754 ~~~~~~~~~~~~~~~~
 755
 756 DELETE
 757 ++++++
 758
 759 Delete all policy instances.
 760
 761 **URL path:**
 762
 763 /deleteinstances
 764
 765 **Parameters:**
 766
 767 None.
 768
 769 **Responses:**
 770
 771 200:
 772
 773 All policy instances deleted.
 774
 775 **Examples:**
 776
 777 **Call**: ::
 778
 779   curl -X DELETE "http://localhost:8085/deleteinstances"
 780
 781 **Result**:
 782
 783 200: ::
 784
 785   All policy instances deleted.
 786
 787 /deletetypes
 788 ~~~~~~~~~~~~
 789
 790 DELETE
 791 ++++++
 792
 793 Delete all policy types.
 794
 795 **URL path:**
 796
 797 /deletetypes
 798
 799 **Parameters:**
 800
 801 None.
 802
 803 **Responses:**
 804
 805 200:
 806
 807 All policy types deleted.
 808
 809 **Examples:**
 810
 811 **Call**: ::
 812
 813   curl -X DELETE "http://localhost:8085/deletetypes"
 814
 815 **Result**:
 816
 817 200: ::
 818
 819   All policy types deleted.
 820
 821 /policytypes
 822 ~~~~~~~~~~~~
 823
 824 PUT
 825 +++
 826
 827 Create or update a policy type.
 828
 829 **URL path:**
 830
 831 /policytypes/{policy-type-id}
 832
 833 **Parameters:**
 834
 835 None.
 836
 837 **Body:** (*Required*)
 838
 839 A JSON object containing the schema for the type.
 840
 841 **Responses:**
 842
 843 200:
 844
 845 The policy type was either created or updated for policy type id: <policy-type-id>
 846
 847 **Examples:**
 848
 849 **Call**: ::
 850
 851   curl -X PUT "http://localhost:8085/policytype/Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 852     -H  "Content-Type: application/json"
 853     -d '{
 854           "$schema": "http://json-schema.org/draft-07/schema#",
 855           "title": "STD_PolicyModelUnconstrained_0.2.0",
 856           "description": "Standard model of a policy with unconstrained scope id combinations",
 857           "type": "object",
 858           "properties": {
 859             "scope": {
 860               "type": "object",
 861               "properties": {
 862                 "ueId": {"type": "string"},
 863                 "groupId": {"type": "string"},
 864                 "sliceId": {"type": "string"},
 865                 "qosId": {"type": "string"},
 866                 "cellId": {"type": "string"}
 867               },
 868               "minProperties": 1,
 869               "additionalProperties": false
 870             },
 871             "qosObjectives": {
 872               "type": "object",
 873               "properties": {
 874                 "gfbr": {"type": "number"},
 875                 "mfbr": {"type": "number"},
 876                 "priorityLevel": {"type": "number"},
 877                 "pdb": {"type": "number"}
 878               },
 879               "additionalProperties": false
 880             },
 881             "qoeObjectives": {
 882               "type": "object",
 883               "properties": {
 884                 "qoeScore": {"type": "number"},
 885                 "initialBuffering": {"type": "number"},
 886                 "reBuffFreq": {"type": "number"},
 887                 "stallRatio": {"type": "number"}
 888               },
 889               "additionalProperties": false
 890             },
 891             "resources": {
 892               "type": "array",
 893               "items": {
 894                 "type": "object",
 895                 "properties": {
 896                   "cellIdList": {
 897                     "type": "array",
 898                     "minItems": 1,
 899                     "uniqueItems": true,
 900                     "items": {
 901                       "type": "string"
 902                     }
 903                   },
 904                   "preference": {
 905                     "type": "string",
 906                     "enum": [
 907                       "SHALL",
 908                       "PREFER",
 909                       "AVOID",
 910                       "FORBID"
 911                     ]
 912                   },
 913                   "primary": {"type": "boolean"}
 914                 },
 915                 "additionalProperties": false,
 916                 "required": ["cellIdList", "preference"]
 917               }
 918             }
 919           },
 920           "minProperties": 2,
 921           "additionalProperties": false,
 922           "required": ["scope"]
 923         }'
 924
 925 **Result**:
 926
 927 200: ::
 928
 929   The policy type was either created or updated for policy type id: STD_PolicyModelUnconstrained_0.2.0
 930
 931 DELETE
 932 ++++++
 933
 934 Delete a policy type.
 935
 936 **URL path:**
 937
 938 /policytypes/{policy-type-id}
 939
 940 **Parameters:**
 941
 942 None.
 943
 944 **Responses:**
 945
 946 200:
 947
 948 policy type successfully deleted for policy type id: <policy-type-id>
 949
 950 **Examples:**
 951
 952 **Call**: ::
 953
 954   curl -X DELETE "http://localhost:8085/policytype?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
 955
 956 **Result**:
 957
 958 200: ::
 959
 960   policy type successfully deleted for policy type id: STD_PolicyModelUnconstrained_0.2.0
 961
 962 /{policyId}/{enforceStatus}
 963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 964
 965 PUT
 966 +++
 967
 968 Set a status to a policy instance with an enforceStatus parameter only.
 969
 970 **URL path:**
 971
 972 /{policyId}/{enforceStatus}
 973
 974 **Parameters:**
 975
 976 None.
 977
 978 **Responses:**
 979
 980 200:
 981
 982 Status updated for policy: <policyId>
 983
 984 **Examples:**
 985
 986 **Call**: ::
 987
 988   curl -X PUT "http://localhost:8085/Policy1/ENFORCED
 989
 990 **Result**:
 991
 992 200: ::
 993
 994   Status updated for policy: Policy1
 995
 996 /{policyId}/{enforceStatus}/{enforceReason}
 997 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 998
 999 PUT
1000 ++++
1001
1002 Send a status to a policy instance with both enforceStatus and enforceReason.
1003
1004 **URL path:**
1005
1006 /{policyId}/{enforceStatus}/{enforceReason}
1007
1008 **Parameters:**
1009
1010 None.
1011
1012 **Responses:**
1013
1014 200:
1015
1016 Status updated for policy: <policyId>
1017
1018 **Examples:**
1019
1020 **Call**: ::
1021
1022   curl -X PUT "http://localhost:8085/Policy1/NOT_ENFORCED/100"
1023
1024 **Result**:
1025
1026 200: ::
1027
1028   Status updated for policy: Policy1