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
5 .. |nbsp| unicode:: 0xA0
8 .. |nbh| unicode:: 0x2011
13 ################################
14 A1 Policy Management Service API
15 ################################
18 *******************************************
19 A1 Policy Management Service - Introduction
20 *******************************************
22 The A1 Policy Management Service ("Policy Agent") is an SMO/NONRTRIC service above the NONRTRIC A1 Adapter/Controller
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 adapter 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 adapter 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
40 ***************************************
41 A1 Policy Management Service - REST NBI
42 ***************************************
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.
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.
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.
56 The Policy Agent NBI has five distinct parts, described in the sections below:
61 * Near-RT RIC Repository
68 A service can register itself in the Policy Agent.
70 By providing a callback URL the service can get notifications from the Policy Agent.
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
99 **Body:** (*Required*)
101 A JSON object (ServiceRegistrationInfo): ::
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.)
121 The ServiceRegistrationInfo is not accepted.
128 curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d '{
129 "callbackUrl": "URL",
130 "keepAliveIntervalSeconds": 0,
131 "serviceName": "existing"
142 curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d "{}"
148 Missing mandatory parameter 'serviceName'
156 Query service information.
163 /services?name=<service-name>
169 The name of the service.
175 Array of JSON objects (ServiceStatus). ::
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)
186 Service is not found.
193 curl -X GET "http://localhost:8081/services?name=existing"
201 "serviceName":"existing",
202 "keepAliveIntervalSeconds":0,
203 "timeSinceLastActivitySeconds":7224,
210 curl -X GET "http://localhost:8081/services?name=nonexistent"
228 /services?name=<service-name>
234 The name of the service.
249 curl -X DELETE "http://localhost:8081/services?name=existing"
259 curl -X DELETE "http://localhost:8081/services?name=nonexistent"
265 Could not find service: nonexistent
273 Heart beat from a service.
280 /services/keepalive?name=<service-name>
286 The name of the service.
296 Service is not found.
303 curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
313 curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
319 Could not find service: nonexistent
321 .. _policy-management:
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.
333 A policy type defines a name and a JSON schema that constrains the content of a policy of that type.
341 Query policy type names.
348 /policy_types?ric=<name-of-ric>
354 The name of the Near |nbh| RT |nbsp| RIC to get types for.
360 Array of policy type names.
364 Near |nbh| RT |nbsp| RIC is not found.
371 curl -X GET "http://localhost:8081/policy_types"
378 "STD_PolicyModelUnconstrained_0.2.0",
379 "Example_QoETarget_1.0.0",
380 "ERIC_QoSNudging_0.2.0"
385 curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
391 org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
399 Returns one policy type schema definition.
406 /policy_schema?id=<name-of-type>
412 The ID of the policy type to get the definition for.
418 Policy schema as JSON schema.
422 Policy type is not found.
429 curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
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",
444 "ueId": {"type": "string"},
445 "groupId": {"type": "string"}
448 "additionalProperties": false
453 "gfbr": {"type": "number"},
454 "mfbr": {"type": "number"}
456 "additionalProperties": false
471 "additionalProperties": false,
472 "required": ["cellIdList"]
477 "additionalProperties": false,
478 "required": ["scope"]
483 curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
489 org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
497 Returns policy type schema definitions.
504 /policy_schemas?ric=<name-of-ric>
510 The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
516 An array of policy schemas as JSON schemas.
520 Near |nbh| RT |nbsp| RIC is not found.
527 curl -X GET "http://localhost:8081/policy_schemas"
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",
546 "additionalProperties": false,
547 "required": ["scope"]
553 "$schema": "http://json-schema.org/draft-07/schema#",
554 "title": "Example_QoETarget_1.0.0",
555 "description": "Example QoE Target policy type",
564 "additionalProperties": false,
565 "required": ["scope"]
573 curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
579 org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
585 Policies can be queried, created, updated, and deleted. A policy is always created in a specific
586 Near |nbh| RT |nbsp| RIC.
588 A policy is defined by its policy type schema.
590 When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
591 it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
592 inconsistency, the Policy Agent will start a synchronization job and try to inconsistency, the Policy Agent will start a
593 synchronization job and try to reset the Near |nbh| RT |nbsp| RIC to its last-known-good status. If this fails, the
594 Policy Agent will clear all policies for the specific Near |nbh| RT |nbsp| RIC in the internal repository and set its
595 state to *UNKNOWN*. This means that no interaction with the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent
596 has been able to contact it again and re-synchronize its state in the repository.
598 Once a service has created a policy, it is the service's responsibility to maintain its life cycle. When a Near |nbh| RT
599 |nbsp| RIC has been restarted, the Policy Agent will try to recreate policies in the Near |nbh| RT |nbsp| RIC according
600 to the policies maintained in its local repository.
601 This means that the service must delete any policies it has created.
602 A policy may be created as a "transient policy", whereby if this policy "disappears" at any stage it will not be
603 re-synchronized to the Near |nbh| RT |nbsp| RIC.
604 For example, this is useful if the policy should not survive a restart of the Near |nbh| RT |nbsp| RIC.
605 A non-transient policy will continue to be maintained in the Near |nbh| RT |nbsp| RIC until it is explicitly deleted
606 (or the service that created it fails to update its Keep Alive status).
608 There are some exceptions where policy instances are not re-synchronized after a Near |nbh| RT |nbsp| RIC restart or
609 when some inconsistency is identified:
611 - The service has registered a "*Keep Alive Interval*", but the service then fails to update its Keep Alive status.
612 - The Policy Agent completely fails to synchronize with a Near |nbh| RT |nbsp| RIC, as described above.
613 - Policies that are marked as transient policies.
628 /policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
634 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
636 service: (*Optional*)
638 The name of the service to get policies for.
642 The name of the policy type to get policies for.
648 Array of JSON objects (PolicyInfo). ::
651 "id": "string", (Identity of the policy)
652 "json": "object", (The configuration of the policy)
653 "lastModified": "string", (Timestamp, last modification time)
654 "ric": "string", (Identity of the target Near |nbh| RT |nbsp| RIC)
655 "service": "string", (The name of the service owning the policy)
656 "type": "string" (Name of the policy type)
660 Near |nbh| RT |nbsp| RIC or policy type not found.
667 curl -X GET "http://localhost:8081/policies?ric=existing"
687 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
689 "service": "Service 1",
690 "type": "STD_PolicyModelUnconstrained_0.2.0"
699 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
701 "service": "Service 2",
702 "type": "Example_QoETarget_1.0.0"
708 curl -X GET "http://localhost:8081/policies?type=nonexistent"
714 Policy type not found
722 Returns a policy configuration.
729 /policy?id=<policy-id>
735 The ID of the policy instance.
741 JSON object containing policy information. ::
744 "id": "string", (ID of policy)
745 "json": "object", (JSON with policy data speified by the type)
746 "ownerServiceName": "string", (Name of the service that created the policy)
747 "ric": "string", (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
748 "type": "string", (Name of the policy type of the policy)
749 "lastModified" (Timestamp, last modification time)
761 curl -X GET "http://localhost:8081/policy?id=Policy 1"
777 "priorityLevel": 268.5,
782 "initialBuffering": 27.75,
788 "ownerServiceName": "Service 1",
790 "type": "STD_PolicyModelUnconstrained_0.2.0",
791 "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
796 curl -X GET "http://localhost:8081/policy?id=nonexistent"
807 Create/Update a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
808 "*Keep Alive Interval*" registered.
815 /policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
821 The ID of the policy instance.
825 The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
827 service: (*Required*)
829 The name of the service creating the policy.
831 transient: (*Optional*)
833 If the policy is transient or not (boolean defaulted to false).
834 A policy is transient if it will be forgotten when the service needs to reconnect to the Near |nbh| RT |nbsp| RIC.
838 The name of the policy type.
840 **Body:** (*Required*)
842 A JSON object containing the data specified by the type.
856 Near |nbh| RT |nbsp| RIC or policy type is not found.
860 Near |nbh| RT |nbsp| RIC is not operational.
867 curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
868 -H "Content-Type: application/json"
877 "priorityLevel": 268.5,
882 "initialBuffering": 27.75,
896 Deletes a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
897 "*Keep Alive Interval*" registered.
904 /policy?id=<policy-id>
910 The ID of the policy instance.
924 Near |nbh| RT |nbsp| RIC is not operational.
931 curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
943 Query policy type IDs.
950 /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
956 The name of the Near |nbh| RT |nbsp| RIC to get policies for.
958 service: (*Optional*)
960 The name of the service to get policies for.
964 The name of the policy type to get policies for.
970 Array of policy type names.
974 RIC or policy type not found.
981 curl -X GET "http://localhost:8081/policy_ids"
995 curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
1009 Returns the status of a policy.
1016 /policy_status?id=<policy-id>
1022 The ID of the policy.
1028 JSON object with policy status.
1034 **********************
1035 Near-RT RIC Repository
1036 **********************
1038 The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
1039 find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
1040 Near |nbh| RT |nbsp| RICs that support a specific policy type.
1048 Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
1055 /ric?managedElementId=<id-of-managed-element>
1059 managedElementId: (*Required*)
1061 The ID of the Managed Element.
1067 Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
1071 No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
1078 curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
1088 curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
1100 Query Near |nbh| RT |nbsp| RIC information.
1107 /rics?policyType=<name-of-policy-type>
1111 policyType: (*Optional*)
1113 The name of the policy type.
1119 Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
1123 "managedElementIds": [
1129 "ricName": "string",
1136 Policy type is not found.
1143 curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
1151 "managedElementIds": [
1156 "STD_PolicyModelUnconstrained_0.2.0",
1157 "Example_QoETarget_1.0.0",
1158 "ERIC_QoSNudging_0.2.0"
1161 "state": "AVAILABLE"
1167 "managedElementIds": [
1171 "STD_PolicyModelUnconstrained_0.2.0"
1174 "state": "UNAVAILABLE"
1180 curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
1186 Policy type not found
1192 The status of the Policy Agent.
1200 Returns the status of the Policy Agent.
1224 curl -X GET "http://localhost:8081/status"
1234 The Policy Agent also provides the possibility to use DMaap to handle policies according to the A1 specification. The
1235 Policy Agent polls the DMaaP Message Router regularly and processes any messages targeted to it. The response is then
1236 published back to the DMaaP Message Router with the result of the call.
1241 The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
1242 :ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
1243 Agent. The "*operation*" can be one of the following: "*GET | PUT | POST | DELETE*". ::
1247 "correlationId": "string",
1249 "timestamp": "timestamp",
1250 "apiVersion": "string",
1251 "originatorId": "string",
1252 "requestId": "string",
1253 "operation": "string",
1260 To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
1265 "correlationId":"c09ac7d1-de62-0016-2000-e63701125557-201",
1266 "target":"policy-agent",
1267 "timestamp":"2019-05-14T11:44:51.36Z",
1269 "originatorId":"849e6c6b420",
1270 "requestId":"23343221",
1272 "url":"/policy_schemas?ric=ric_ric-simulator_1"
1278 The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
1279 "*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
1282 "requestId": "string",
1283 "correlationId": "string",
1284 "originatorId": "string",
1286 "message": "string",
1288 "timestamp": "string",
1295 The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
1296 the Policy Agent: ::
1299 \"requestId\":\"23343221\",
1300 \"correlationId\":\"c09ac7d1-de62-0016-2000-e63701125557-201\",
1301 \"originatorId\":\"849e6c6b420\",
1302 \"type\":\"response\",
1305 \\\"$schema\\\":\\\"http://json-schema.org/draft-07/schema#\\\",
1306 \\\"description\\\":\\\"QoS policy type\\\",
1307 \\\"title\\\":\\\"STD_QoSNudging_0.2.0\\\",
1308 \\\"type\\\":\\\"object\\\",
1309 \\\"properties\\\":{\\\"scope\\\":{\\\"additionalProperties\\\":true,
1310 \\\"type\\\":\\\"object\\\",
1311 \\\"properties\\\":{\\\"qosId\\\":{\\\"type\\\":\\\"string\\\"},
1312 \\\"ueId\\\":{\\\"type\\\":\\\"string\\\"}},
1313 \\\"required\\\":[\\\"ueId\\\",
1315 \\\"statement\\\":{\\\"additionalProperties\\\":false,
1316 \\\"type\\\":\\\"object\\\",
1317 \\\"properties\\\":{\\\"priorityLevel\\\":{\\\"type\\\":\\\"number\\\"}},
1318 \\\"required\\\":[\\\"priorityLevel\\\"]}}
1321 \"timestamp\":\"2019-05-14T11:44:51.36Z\",
1322 \"status\":\"200 OK\"