Merge "First version of HealtCheck test"
[nonrtric.git] / docs / policy-agent-api.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright (C) 2020 Nordix
4
5 .. |nbsp| unicode:: 0xA0
6    :trim:
7
8 .. |nbh| unicode:: 0x2011
9    :trim:
10
11 .. _policy-agent-api:
12
13 ################################
14 A1 Policy Management Service API
15 ################################
16
17
18 *******************************************
19 A1 Policy Management Service - Introduction
20 *******************************************
21
22 The A1 Policy Management Service ("Policy Agent") is an SMO/NONRTRIC service above the NONRTRIC A1 Adaptor/Controller
23 that provides:
24
25 * Unified REST & DMAAP APIs for managing A1 Policies in all Near |nbh| RT |nbsp| RICs
26 * Synchronized view of registered "services" (e.g. R-APP, GUI, etc)
27 * Synchronized view of policy instances for each "service"
28 * Synchronized view of policy instances in all Near |nbh| RT |nbsp| RICs
29 * Synchronized view of policy types in all Near |nbh| RT |nbsp| RICs
30 * Policy Query API (e.g. per Near |nbh| RT |nbsp| RIC, per "service", per policy type)
31 * An initial interface for unified Near |nbh| RT |nbsp| RIC ID to Near |nbh| RT |nbsp| RIC address mapping.
32   (Note:  may also later act as adaptor to A&AI, CMDBs etc. to "find" Near |nbh| RT |nbsp| RICs - TBC)
33 * An Initial "O1 ManagedElement" mapping database & interface to find appropriate Near |nbh| RT |nbsp| RIC for RAN elements.
34   (Note: may also later act as adaptor to A&AI, RuntimeDB, other CMDBs etc. - TBC)
35 * Monitors all Near |nbh| RT |nbsp| RICs and recovers from inconsistencies (Note: e.g. Near |nbh| RT |nbsp| RIC restarts)
36 * Support for different Southbound connectors on a per Near |nbh| RT |nbsp| RIC basis. (Note: e.g. different A1
37   versions, different Near |nbh| RT |nbsp| RIC versions, different A1 adapters, different or proprietary A1
38   controllers/EMSs)
39
40 ***************************************
41 A1 Policy Management Service - REST NBI
42 ***************************************
43
44 This is the north bound API of the A1 Policy Management Service ("Policy Agent"). This API allows *services* to interact
45 with the Policy Agent using REST.
46
47 By registering with the Policy Agent, the Policy Agent takes responsibility for synchronizing the policies created by
48 the service in the Near |nbh| RT |nbsp| RICs. This means that if a Near |nbh| RT |nbsp| RIC restarts, the Policy Agent
49 will try to recreate all the policies residing in the Near |nbh| RT |nbsp| RIC once it is started again. If this is not
50 possible, it will remove all policies belonging to the Near |nbh| RT |nbsp| RIC.
51
52 The Policy Agent also keeps an updated view of the policy types available, and which Near |nbh| RT |nbsp| RICs that
53 support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain
54 Near |nbh| RT |nbsp| RIC.
55
56 The Policy Agent NBI has five distinct parts, described in the sections below:
57
58 * Service Management
59 * Policy Types
60 * Policy Management
61 * Near-RT RIC Repository
62 * Health Check
63
64 ******************
65 Service Management
66 ******************
67
68 A service can register itself in the Policy Agent.
69
70 By providing a callback URL the service can get notifications from the Policy Agent.
71
72 A service can also register a "*Keep Alive Interval*", in seconds. By doing this the service promises to call the
73 Policy Agent's "*Keep Alive*" method, or else create or delete policies, more often than the "*Keep Alive Interval*"
74 measured in seconds. If the service, for some reason, is not able to do this, the Policy Agent will consider that the
75 service has died or vanished and will then delete all its policies, both in the internal repository and in the
76 Near |nbh| RT |nbsp| RICs where they were earlier created. **Note!** |nbsp| If the service does not provide a value for
77 "*Keep Alive Interval*", then the service maintains full responsibility to delete all of its policies when they are no
78 longer needed.
79
80 /service
81 ~~~~~~~~
82
83 PUT
84 +++
85
86 Register a service.
87
88 Definition
89 """"""""""
90
91 **URL path:**
92
93 /service
94
95 **Parameters:**
96
97 None.
98
99 **Body:**  (*Required*)
100
101 A JSON object (ServiceRegistrationInfo): ::
102
103   {
104     "callbackUrl": "string",         (An empty string means the service will never get any callbacks.)
105     "keepAliveIntervalSeconds": 0,   (0 means the service will always be considered alive.)
106     "serviceName": "string"          (Required, must be unique.)
107   }
108
109 **Responses:**
110
111 200:
112
113 Service updated.
114
115 201:
116
117 Service created.
118
119 400:
120
121 The ServiceRegistrationInfo is not accepted.
122
123 Examples
124 """"""""
125
126 **Call**: ::
127
128   curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d '{
129       "callbackUrl": "URL",
130       "keepAliveIntervalSeconds": 0,
131       "serviceName": "existing"
132     }'
133
134 **Result**:
135
136 201: ::
137
138    OK
139
140 **Call**: ::
141
142    curl -X PUT "http://localhost:8081/service" -H  "Content-Type: application/json" -d "{}"
143
144 **Result**:
145
146 400: ::
147
148   Missing mandatory parameter 'serviceName'
149
150 /services
151 ~~~~~~~~~
152
153 GET
154 +++
155
156 Query service information.
157
158 Definition
159 """"""""""
160
161 **URL path:**
162
163 /services?name=<service-name>
164
165 **Parameters:**
166
167 name: (*Optional*)
168
169 The name of the service.
170
171 **Responses:**
172
173 200:
174
175 Array of JSON objects (ServiceStatus). ::
176
177   {
178     "callbackUrl": "string",             (Callback URL)
179     "keepAliveIntervalSeconds": 0,       (Policy keep alive interval)
180     "serviceName": "string",             (Identity of the service)
181     "timeSinceLastActivitySeconds": 0    (Time since last invocation by the service)
182   }
183
184 404:
185
186 Service is not found.
187
188 Examples
189 """"""""
190
191 **Call**: ::
192
193   curl -X GET "http://localhost:8081/services?name=existing"
194
195 **Result**:
196
197 200: ::
198
199   [
200     {
201       "serviceName":"existing",
202       "keepAliveIntervalSeconds":0,
203       "timeSinceLastActivitySeconds":7224,
204       "callbackUrl":"URL"
205     }
206   ]
207
208 **Call**: ::
209
210   curl -X GET "http://localhost:8081/services?name=nonexistent"
211
212 Result:
213
214 404: ::
215
216   Service not found
217
218 DELETE
219 ++++++
220
221 Delete a service.
222
223 Definition
224 """"""""""
225
226 **URL path:**
227
228 /services?name=<service-name>
229
230 **Parameters:**
231
232 name: (*Required*)
233
234 The name of the service.
235
236 **Responses:**
237
238 204:
239   OK
240
241 404:
242   Service not found.
243
244 Examples
245 """"""""
246
247 **Call**: ::
248
249   curl -X DELETE "http://localhost:8081/services?name=existing"
250
251 **Result**:
252
253 204: ::
254
255   OK
256
257 **Call**: ::
258
259   curl -X DELETE "http://localhost:8081/services?name=nonexistent"
260
261 Result:
262
263 404: ::
264
265   Could not find service: nonexistent
266
267 /services/keepalive
268 ~~~~~~~~~~~~~~~~~~~
269
270 PUT
271 +++
272
273 Heart beat from a service.
274
275 Definition
276 """"""""""
277
278 **URL path:**
279
280 /services/keepalive?name=<service-name>
281
282 **Parameters:**
283
284 name: (*Required*)
285
286 The name of the service.
287
288 **Responses:**
289
290 200:
291
292 OK
293
294 404:
295
296 Service is not found.
297
298 Examples
299 """"""""
300
301 **Call**: ::
302
303   curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
304
305 **Result**:
306
307 200: ::
308
309   OK
310
311 **Call**: ::
312
313   curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
314
315 **Result**:
316
317 404: ::
318
319   Could not find service: nonexistent
320
321 .. _policy-management:
322
323 ************
324 Policy Types
325 ************
326
327 Policies are based on types. The set of available policy types is determined by the set of policy types supported by
328 Near |nbh| RT |nbsp| RICs. At startup, the Policy Agent queries all Near |nbh| RT |nbsp| RICs for their supported types
329 and stores them in its internal repository. It then checks this at regular intervals to keep the repository of types up
330 to date. Policy types cannot be created, updated or deleted using this interface since this must be done via the
331 Near |nbh| RT |nbsp| RICs.
332
333 A policy type defines a name and a JSON schema that constrains the content of a policy of that type.
334
335 /policy_types
336 ~~~~~~~~~~~~~
337
338 GET
339 +++
340
341 Query policy type names.
342
343 Definition
344 """"""""""
345
346 **URL path:**
347
348 /policy_types?ric=<name-of-ric>
349
350 **Parameters:**
351
352 ric: (*Optional*)
353
354 The name of the Near |nbh| RT |nbsp| RIC to get types for.
355
356 **Responses:**
357
358 200:
359
360   Array of policy type names.
361
362 404:
363
364   Near |nbh| RT |nbsp| RIC is not found.
365
366 Examples
367 """"""""
368
369 **Call**: ::
370
371   curl -X GET "http://localhost:8081/policy_types"
372
373 **Result**:
374
375 200: ::
376
377   [
378     "STD_PolicyModelUnconstrained_0.2.0",
379     "Example_QoETarget_1.0.0",
380     "ERIC_QoSNudging_0.2.0"
381   ]
382
383 **Call**: ::
384
385   curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
386
387 **Result**:
388
389 404: ::
390
391   org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
392
393 /policy_schema
394 ~~~~~~~~~~~~~~
395
396 GET
397 +++
398
399 Returns one policy type schema definition.
400
401 Definition
402 """"""""""
403
404 **URL path:**
405
406 /policy_schema?id=<name-of-type>
407
408 **Parameters:**
409
410 id: (*Required*)
411
412 The ID of the policy type to get the definition for.
413
414 **Responses:**
415
416 200:
417
418 Policy schema as JSON schema.
419
420 404:
421
422 Policy type is not found.
423
424 Examples
425 """"""""
426
427 **Call**: ::
428
429  curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
430
431 **Result**:
432
433 200: ::
434
435   {
436     "$schema": "http://json-schema.org/draft-07/schema#",
437     "title": "STD_PolicyModelUnconstrained_0.2.0",
438     "description": "Standard model of a policy with unconstrained scope id combinations",
439     "type": "object",
440     "properties": {
441      "scope": {
442         "type": "object",
443         "properties": {
444           "ueId": {"type": "string"},
445           "groupId": {"type": "string"}
446         },
447         "minProperties": 1,
448         "additionalProperties": false
449       },
450       "qosObjectives": {
451         "type": "object",
452         "properties": {
453           "gfbr": {"type": "number"},
454           "mfbr": {"type": "number"}
455         },
456         "additionalProperties": false
457       },
458       "resources": {
459         "type": "array",
460         "items": {
461           "type": "object",
462           "properties": {
463             "cellIdList": {
464               "type": "array",
465               "minItems": 1,
466               "uniqueItems": true,
467               "items": {
468                 "type": "string"
469               }
470             },
471           "additionalProperties": false,
472           "required": ["cellIdList"]
473         }
474       }
475     },
476     "minProperties": 1,
477     "additionalProperties": false,
478     "required": ["scope"]
479   }
480
481 **Call**: ::
482
483   curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
484
485 **Result**:
486
487 404: ::
488
489   org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
490
491 /policy_schemas
492 ~~~~~~~~~~~~~~~
493
494 GET
495 +++
496
497 Returns policy type schema definitions.
498
499 Definition
500 """"""""""
501
502 **URL path:**
503
504 /policy_schemas?ric=<name-of-ric>
505
506 **Parameters:**
507
508 ric: (*Optional*)
509
510 The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
511
512 **Responses:**
513
514 200:
515
516 An array of policy schemas as JSON schemas.
517
518 404:
519
520 Near |nbh| RT |nbsp| RIC is not found.
521
522 Examples
523 """"""""
524
525 **Call**: ::
526
527   curl -X GET "http://localhost:8081/policy_schemas"
528
529 **Result**:
530
531 200: ::
532
533   [
534     {
535       "$schema": "http://json-schema.org/draft-07/schema#",
536       "title": "STD_PolicyModelUnconstrained_0.2.0",
537       "description": "Standard model of a policy with unconstrained scope id combinations",
538       "type": "object",
539       "properties": {
540         "scope": {
541           "type": "object",
542             .
543             .
544             .
545         }
546         "additionalProperties": false,
547         "required": ["scope"]
548       },
549         .
550         .
551         .
552       {
553         "$schema": "http://json-schema.org/draft-07/schema#",
554         "title": "Example_QoETarget_1.0.0",
555         "description": "Example QoE Target policy type",
556         "type": "object",
557           "properties": {
558             "scope": {
559               "type": "object",
560                 .
561                 .
562                 .
563             }
564             "additionalProperties": false,
565            "required": ["scope"]
566         }
567       }
568     }
569   ]
570
571 **Call**: ::
572
573   curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
574
575 **Result**:
576
577 404: ::
578
579   org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
580
581 *****************
582 Policy Management
583 *****************
584
585 Policies can be queried, created, updated, and deleted. A policy is always created in a specific
586 Near |nbh| RT |nbsp| RIC.
587
588 When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
589 it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
590 inconsistency, the Policy Agent will start a synchronization job and try to reflect the status of the
591 Near |nbh| RT |nbsp| RIC. If this fails, the Policy Agent will delete all policies for the specific
592 Near |nbh| RT |nbsp| RIC in the internal repository and set its state to *UNKNOWN*. This means that no interaction with
593 the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent has been able to contact it again and re-synchronize its
594 state in the repository.
595
596 A policy is defined by its type schema.
597
598 Once a service has created a policy, it is the service's responsibility to maintain its life cycle. Since policies are
599 transient, they will not survive a restart of a Near |nbh| RT |nbsp| RIC. But this is handled by the Policy Agent. When
600 a Near |nbh| RT |nbsp| RIC has been restarted, the Policy Agent will try to recreate the policies in the
601 Near |nbh| RT |nbsp| RIC that are stored in its local repository. This means that the service always must delete any
602 policy it has created. There are only two exceptions, see below:
603
604 - The service has registered a "*Keep Alive Interval*", then its policies will be deleted if it fails to notify the
605   Policy Agent in due time.
606 - The Policy Agent completely fails to synchronize with a Near |nbh| RT |nbsp| RIC.
607
608 /policies
609 ~~~~~~~~~
610
611 GET
612 +++
613
614 Query policies.
615
616 Definition
617 """"""""""
618
619 **URL path:**
620
621 /policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
622
623 **Parameters:**
624
625 ric: (*Optional*)
626
627 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
628
629 service: (*Optional*)
630
631 The name of the service to get policies for.
632
633 type: (*Optional*)
634
635 The name of the policy type to get policies for.
636
637 **Responses:**
638
639 200:
640
641 Array of JSON objects (PolicyInfo). ::
642
643   {
644     "id": "string",              (Identity of the policy)
645     "json": "object",            (The configuration of the policy)
646     "lastModified": "string",    (Timestamp, last modification time)
647     "ric": "string",             (Identity of the target Near |nbh| RT |nbsp| RIC)
648     "service": "string",         (The name of the service owning the policy)
649     "type": "string"             (Name of the policy type)
650   }
651
652 404:
653   Near |nbh| RT |nbsp| RIC or policy type not found.
654
655 Examples
656 """"""""
657
658 **Call**: ::
659
660   curl -X GET "http://localhost:8081/policies?ric=existing"
661
662 **Result**:
663
664 200: ::
665
666   [
667     {
668       "id": "Policy 1",
669       "json": {
670         "scope": {
671           "ueId": "UE 1",
672           "groupId": "Group 1"
673         },
674         "qosObjectives": {
675           "gfbr": 1,
676           "mfbr": 2
677         },
678         "cellId": "Cell 1"
679       },
680       "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
681       "ric": "existing",
682       "service": "Service 1",
683       "type": "STD_PolicyModelUnconstrained_0.2.0"
684     },
685     {
686       "id": "Policy 2",
687       "json": {
688           .
689           .
690           .
691       },
692       "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
693       "ric": "existing",
694       "service": "Service 2",
695       "type": "Example_QoETarget_1.0.0"
696     }
697   ]
698
699 **Call**: ::
700
701   curl -X GET "http://localhost:8081/policies?type=nonexistent"
702
703 **Result**:
704
705 404: ::
706
707   Policy type not found
708
709 /policy
710 ~~~~~~~
711
712 GET
713 +++
714
715 Returns a policy configuration.
716
717 Definition
718 """"""""""
719
720 **URL path:**
721
722 /policy?id=<policy-id>
723
724 **Parameters:**
725
726 id: (*Required*)
727
728 The ID of the policy instance.
729
730 **Responses:**
731
732 200:
733
734 JSON object containing policy information. ::
735
736   {
737     "id": "string",                  (ID of policy)
738     "json": "object",                (JSON with policy data speified by the type)
739     "ownerServiceName": "string",    (Name of the service that created the policy)
740     "ric": "string",                 (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
741     "type": "string",                (Name of the policy type of the policy)
742     "lastModified"                   (Timestamp, last modification time)
743   }
744
745 404:
746
747 Policy is not found.
748
749 Examples
750 """"""""
751
752 **Call**: ::
753
754   curl -X GET "http://localhost:8081/policy?id=Policy 1"
755
756 **Result**:
757
758 200: ::
759
760   {
761     "id": "Policy 1",
762     "json", {
763       "scope": {
764         "ueId": "UE1 ",
765         "cellId": "Cell 1"
766       },
767       "qosObjectives": {
768         "gfbr": 319.5,
769         "mfbr": 782.75,
770         "priorityLevel": 268.5,
771         "pdb": 44.0
772       },
773       "qoeObjectives": {
774         "qoeScore": 329.0,
775         "initialBuffering": 27.75,
776         "reBuffFreq": 539.0,
777         "stallRatio": 343.0
778       },
779       "resources": []
780     },
781     "ownerServiceName": "Service 1",
782     "ric": "ric1",
783     "type": "STD_PolicyModelUnconstrained_0.2.0",
784     "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
785   }
786
787 **Call**: ::
788
789   curl -X GET "http://localhost:8081/policy?id=nonexistent"
790
791 **Result**:
792
793 404: ::
794
795   Policy is not found
796
797 PUT
798 +++
799
800 Create/Update a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
801 "*Keep Alive Interval*" registered.
802
803 Definition
804 """"""""""
805
806 **URL path:**
807
808 /policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
809
810 **Parameters:**
811
812 id: (*Required*)
813
814 The ID of the policy instance.
815
816 ric: (*Required*)
817
818 The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
819
820 service: (*Required*)
821
822 The name of the service creating the policy.
823
824 type: (*Optional*)
825
826 The name of the policy type.
827
828 **Body:** (*Required*)
829
830 A JSON object containing the data specified by the type.
831
832 **Responses:**
833
834 200:
835
836 Policy updated.
837
838 201:
839
840 Policy created.
841
842 404:
843
844 Near |nbh| RT |nbsp| RIC or policy type is not found.
845
846 423:
847
848 Near |nbh| RT |nbsp| RIC is not operational.
849
850 Examples
851 """"""""
852
853 **Call**: ::
854
855   curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
856     -H  "Content-Type: application/json"
857     -d '{
858           "scope": {
859             "ueId": "UE 1",
860             "cellId": "Cell 1"
861           },
862           "qosObjectives": {
863             "gfbr": 319.5,
864             "mfbr": 782.75,
865             "priorityLevel": 268.5,
866             "pdb": 44.0
867           },
868           "qoeObjectives": {
869             "qoeScore": 329.0,
870             "initialBuffering": 27.75,
871             "reBuffFreq": 539.0,
872             "stallRatio": 343.0
873           },
874           "resources": []
875         }'
876
877 **Result**:
878
879 200
880
881 DELETE
882 ++++++
883
884 Deletes a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
885 "*Keep Alive Interval*" registered.
886
887 Definition
888 """"""""""
889
890 **URL path:**
891
892 /policy?id=<policy-id>
893
894 **Parameters:**
895
896 id: (*Required*)
897
898 The ID of the policy instance.
899
900 **Responses:**
901
902 204:
903
904 Policy deleted.
905
906 404:
907
908 Policy is not found.
909
910 423:
911
912 Near |nbh| RT |nbsp| RIC is not operational.
913
914 Examples
915 """"""""
916
917 **Call**: ::
918
919   curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
920
921 **Result**:
922
923 204
924
925 /policy_ids
926 ~~~~~~~~~~~
927
928 GET
929 +++
930
931 Query policy type IDs.
932
933 Definition
934 """"""""""
935
936 **URL path:**
937
938 /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
939
940 **Parameters:**
941
942 ric: (*Optional*)
943
944 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
945
946 service: (*Optional*)
947
948 The name of the service to get policies for.
949
950 type: (*Optional*)
951
952 The name of the policy type to get policies for.
953
954 **Responses:**
955
956 200:
957
958 Array of policy type names.
959
960 404:
961
962 RIC or policy type not found.
963
964 Examples
965 """"""""
966
967 **Call**: ::
968
969   curl -X GET "http://localhost:8081/policy_ids"
970
971 **Result**:
972
973 200: ::
974
975   [
976     "Policy 1",
977     "Policy 2",
978     "Policy 3"
979   ]
980
981 **Call**: ::
982
983   curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
984
985 **Result**:
986
987 404: ::
988
989   Ric not found
990
991 /policy_status
992 ~~~~~~~~~~~~~~
993
994 GET
995 +++
996
997 Returns the status of a policy.
998
999 Definition
1000 """"""""""
1001
1002 **URL path:**
1003
1004 /policy_status?id=<policy-id>
1005
1006 **Parameters:**
1007
1008 id: (*Required*)
1009
1010 The ID of the policy.
1011
1012 **Responses:**
1013
1014 200:
1015
1016 JSON object with policy status.
1017
1018 404:
1019
1020 Policy not found.
1021
1022 **********************
1023 Near-RT RIC Repository
1024 **********************
1025
1026 The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
1027 find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
1028 Near |nbh| RT |nbsp| RICs that support a specific policy type.
1029
1030 /ric
1031 ~~~~
1032
1033 GET
1034 +++
1035
1036 Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
1037
1038 Definition
1039 """"""""""
1040
1041 **URL path:**
1042
1043 /ric?managedElementId=<id-of-managed-element>
1044
1045 **Parameters:**
1046
1047 managedElementId: (*Required*)
1048
1049 The ID of the Managed Element.
1050
1051 **Responses:**
1052
1053 200:
1054
1055 Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
1056
1057 404:
1058
1059 No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
1060
1061 Examples
1062 """"""""
1063
1064 **Call**: ::
1065
1066   curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
1067
1068 **Result**:
1069
1070 200: ::
1071
1072   Ric 1
1073
1074 **Call**: ::
1075
1076   curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
1077
1078 **Result**:
1079
1080 404
1081
1082 /rics
1083 ~~~~~
1084
1085 GET
1086 +++
1087
1088 Query Near |nbh| RT |nbsp| RIC information.
1089
1090 Definition
1091 """"""""""
1092
1093 **URL path:**
1094
1095 /rics?policyType=<name-of-policy-type>
1096
1097 **Parameters:**
1098
1099 policyType: (*Optional*)
1100
1101 The name of the policy type.
1102
1103 **Responses:**
1104
1105 200:
1106
1107 Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
1108
1109   [
1110     {
1111       "managedElementIds": [
1112         "string"
1113       ],
1114       "policyTypes": [
1115         "string"
1116       ],
1117       "ricName": "string",
1118       "state": "string"
1119     }
1120   ]
1121
1122 404:
1123
1124 Policy type is not found.
1125
1126 Examples
1127 """"""""
1128
1129 **Call**: ::
1130
1131   curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
1132
1133 **Result**:
1134
1135 200: ::
1136
1137   [
1138     {
1139       "managedElementIds": [
1140         "ME 1",
1141         "ME 2"
1142       ],
1143       "policyTypes": [
1144         "STD_PolicyModelUnconstrained_0.2.0",
1145         "Example_QoETarget_1.0.0",
1146         "ERIC_QoSNudging_0.2.0"
1147       ],
1148       "ricName": "Ric 1",
1149       "state": "AVAILABLE"
1150     },
1151       .
1152       .
1153       .
1154     {
1155       "managedElementIds": [
1156         "ME 3"
1157       ],
1158       "policyTypes": [
1159         "STD_PolicyModelUnconstrained_0.2.0"
1160       ],
1161       "ricName": "Ric X",
1162       "state": "UNAVAILABLE"
1163     }
1164   ]
1165
1166 **Call**: ::
1167
1168   curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
1169
1170 **Result**:
1171
1172 404: ::
1173
1174   Policy type not found
1175
1176 ************
1177 Health Check
1178 ************
1179
1180 The status of the Policy Agent.
1181
1182 /status
1183 ~~~~~~~
1184
1185 GET
1186 +++
1187
1188 Returns the status of the Policy Agent.
1189
1190 Definition
1191 """"""""""
1192
1193 **URL path:**
1194
1195 /status
1196
1197 **Parameters:**
1198
1199 None.
1200
1201 **Responses:**
1202
1203 200:
1204
1205 Service is living.
1206
1207 Examples
1208 """"""""
1209
1210 **Call**: ::
1211
1212   curl -X GET "http://localhost:8081/status"
1213
1214 **Result**:
1215
1216 200
1217
1218 ****************
1219 A1 through DMaaP
1220 ****************
1221
1222 The Policy Agent also provides the possibility to use DMaap to handle policies according to the A1 specification. The
1223 Policy Agent polls the DMaaP Message Router regularly and processes any messages targeted to it. The response is then
1224 published back to the DMaaP Message Router with the result of the call.
1225
1226 Send Message
1227 ~~~~~~~~~~~~
1228
1229 The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
1230 :ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
1231 Agent. The "*operation*" can be one of the following: "*GET | PUT | POST | DELETE*". ::
1232
1233   {
1234     "type": "string",
1235     "correlationId": "string",
1236     "target": "string",
1237     "timestamp": "timestamp",
1238     "apiVersion": "string",
1239     "originatorId": "string",
1240     "requestId": "string",
1241     "operation": "string",
1242     "url": "string"
1243   }
1244
1245 Example
1246 +++++++
1247
1248 To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
1249 Router: ::
1250
1251   {
1252     "type":"request",
1253     "correlationId":"c09ac7d1-de62-0016-2000-e63701125557-201",
1254     "target":"policy-agent",
1255     "timestamp":"2019-05-14T11:44:51.36Z",
1256     "apiVersion":"1.0",
1257     "originatorId":"849e6c6b420",
1258     "requestId":"23343221",
1259     "operation":"GET",
1260     "url":"/policy_schemas?ric=ric_ric-simulator_1"
1261   }
1262
1263 Receive Message
1264 ~~~~~~~~~~~~~~~
1265
1266 The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
1267 "*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
1268
1269   {
1270     "requestId": "string",
1271     "correlationId": "string",
1272     "originatorId": "string",
1273     "type": "string",
1274     "message": "string",
1275     "type":  "string",
1276     "timestamp": "string",
1277     "status": "string"
1278   }
1279
1280 Example
1281 +++++++
1282
1283 The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
1284 the Policy Agent: ::
1285
1286   {
1287     \"requestId\":\"23343221\",
1288     \"correlationId\":\"c09ac7d1-de62-0016-2000-e63701125557-201\",
1289     \"originatorId\":\"849e6c6b420\",
1290     \"type\":\"response\",
1291     \"message\":\"[
1292       {
1293       \\\"$schema\\\":\\\"http://json-schema.org/draft-07/schema#\\\",
1294       \\\"description\\\":\\\"QoS policy type\\\",
1295       \\\"title\\\":\\\"STD_QoSNudging_0.2.0\\\",
1296       \\\"type\\\":\\\"object\\\",
1297       \\\"properties\\\":{\\\"scope\\\":{\\\"additionalProperties\\\":true,
1298       \\\"type\\\":\\\"object\\\",
1299       \\\"properties\\\":{\\\"qosId\\\":{\\\"type\\\":\\\"string\\\"},
1300       \\\"ueId\\\":{\\\"type\\\":\\\"string\\\"}},
1301       \\\"required\\\":[\\\"ueId\\\",
1302       \\\"qosId\\\"]},
1303       \\\"statement\\\":{\\\"additionalProperties\\\":false,
1304       \\\"type\\\":\\\"object\\\",
1305       \\\"properties\\\":{\\\"priorityLevel\\\":{\\\"type\\\":\\\"number\\\"}},
1306       \\\"required\\\":[\\\"priorityLevel\\\"]}}
1307       }
1308     ]\",
1309     \"timestamp\":\"2019-05-14T11:44:51.36Z\",
1310     \"status\":\"200 OK\"
1311   }