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