Cherry Maintenance Doc updates
[sim/a1-interface.git] / 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