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