Change formatting of API documentation
Changed the headings and added a heading level for the definition and
example of use of a function.
Change-Id: Ifab8b13aabb21cd1692a3e700969d8d926b4ccfb
Issue-ID: NONRTRIC-158
Signed-off-by: elinuxhenrik <henrik.b.andersson@est.tech>
diff --git a/docs/policy-agent-api.rst b/docs/policy-agent-api.rst
index 7161bdf..ce94b3d 100644
--- a/docs/policy-agent-api.rst
+++ b/docs/policy-agent-api.rst
@@ -10,9 +10,9 @@
.. _policy-agent-api:
-############################
-A1 Policy Management Service
-############################
+################################
+A1 Policy Management Service API
+################################
*******************************************
@@ -53,15 +53,17 @@
support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain
Near |nbh| RT |nbsp| RIC.
-The Policy Agent NBI has four distinct parts, described in the sections below:
+The Policy Agent NBI has five distinct parts, described in the sections below:
* Service Management
+* Policy Types
* Policy Management
* Near-RT RIC Repository
* Health Check
+******************
Service Management
-==================
+******************
A service can register itself in the Policy Agent.
@@ -75,9 +77,6 @@
"*Keep Alive Interval*", then the service maintains full responsibility to delete all of its policies when they are no
longer needed.
-Service Management Operations
------------------------------
-
/service
~~~~~~~~
@@ -86,51 +85,67 @@
Register a service.
+Definition
+""""""""""
+
**URL path:**
- /service
+
+/service
**Parameters:**
- None.
+
+None.
**Body:** (*Required*)
- A JSON object (ServiceRegistrationInfo): ::
- {
- "callbackUrl": "string", (An empty string means the service will never get any callbacks.)
- "keepAliveIntervalSeconds": 0, (0 means the service will always be considered alive.)
- "serviceName": "string" (Required, must be unique.)
- }
+A JSON object (ServiceRegistrationInfo): ::
+
+ {
+ "callbackUrl": "string", (An empty string means the service will never get any callbacks.)
+ "keepAliveIntervalSeconds": 0, (0 means the service will always be considered alive.)
+ "serviceName": "string" (Required, must be unique.)
+ }
**Responses:**
- 200:
- Service updated.
- 201:
- Service created.
- 400:
- The ServiceRegistrationInfo is not accepted.
-**Examples:**
- **Call**: ::
+200:
- curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d '{
- "callbackUrl": "URL",
- "keepAliveIntervalSeconds": 0,
- "serviceName": "existing"
- }'
+Service updated.
- Result:
- 201: ::
+201:
- OK
+Service created.
- **Call**: ::
+400:
- curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d "{}"
+The ServiceRegistrationInfo is not accepted.
- Result:
- 400: ::
+Examples
+""""""""
- Missing mandatory parameter 'serviceName'
+**Call**: ::
+
+ curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d '{
+ "callbackUrl": "URL",
+ "keepAliveIntervalSeconds": 0,
+ "serviceName": "existing"
+ }'
+
+**Result**:
+
+201: ::
+
+ OK
+
+**Call**: ::
+
+ curl -X PUT "http://localhost:8081/service" -H "Content-Type: application/json" -d "{}"
+
+**Result**:
+
+400: ::
+
+ Missing mandatory parameter 'serviceName'
/services
~~~~~~~~~
@@ -140,88 +155,114 @@
Query service information.
+Definition
+""""""""""
+
**URL path:**
- /services?name=<service-name>
+
+/services?name=<service-name>
**Parameters:**
- name: (*Optional*)
- The name of the service.
+
+name: (*Optional*)
+
+The name of the service.
**Responses:**
- 200:
- Array of JSON objects (ServiceStatus). ::
- {
- "callbackUrl": "string", (Callback URL)
- "keepAliveIntervalSeconds": 0, (Policy keep alive interval)
- "serviceName": "string", (Identity of the service)
- "timeSinceLastActivitySeconds": 0 (Time since last invocation by the service)
- }
- 404:
- Service is not found.
+200:
-**Examples:**
- **Call**: ::
+Array of JSON objects (ServiceStatus). ::
- curl -X GET "http://localhost:8081/services?name=existing"
+ {
+ "callbackUrl": "string", (Callback URL)
+ "keepAliveIntervalSeconds": 0, (Policy keep alive interval)
+ "serviceName": "string", (Identity of the service)
+ "timeSinceLastActivitySeconds": 0 (Time since last invocation by the service)
+ }
- Result:
- 200: ::
+404:
- [
- {
- "serviceName":"existing",
- "keepAliveIntervalSeconds":0,
- "timeSinceLastActivitySeconds":7224,
- "callbackUrl":"URL"
- }
- ]
+Service is not found.
- **Call**: ::
+Examples
+""""""""
- curl -X GET "http://localhost:8081/services?name=nonexistent"
+**Call**: ::
- Result:
- 404: ::
+ curl -X GET "http://localhost:8081/services?name=existing"
- Service not found
+**Result**:
+
+200: ::
+
+ [
+ {
+ "serviceName":"existing",
+ "keepAliveIntervalSeconds":0,
+ "timeSinceLastActivitySeconds":7224,
+ "callbackUrl":"URL"
+ }
+ ]
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/services?name=nonexistent"
+
+Result:
+
+404: ::
+
+ Service not found
DELETE
++++++
Delete a service.
+Definition
+""""""""""
+
**URL path:**
- /services?name=<service-name>
+
+/services?name=<service-name>
**Parameters:**
- name: (*Required*)
- The name of the service.
+
+name: (*Required*)
+
+The name of the service.
**Responses:**
- 204:
- OK
- 404:
- Service not found.
-**Examples:**
- **Call**: ::
+204:
+ OK
- curl -X DELETE "http://localhost:8081/services?name=existing"
+404:
+ Service not found.
- Result:
- 204: ::
+Examples
+""""""""
- OK
+**Call**: ::
- **Call**: ::
+ curl -X DELETE "http://localhost:8081/services?name=existing"
- curl -X DELETE "http://localhost:8081/services?name=nonexistent"
+**Result**:
- Result:
- 404: ::
+204: ::
- Could not find service: nonexistent
+ OK
+
+**Call**: ::
+
+ curl -X DELETE "http://localhost:8081/services?name=nonexistent"
+
+Result:
+
+404: ::
+
+ Could not find service: nonexistent
/services/keepalive
~~~~~~~~~~~~~~~~~~~
@@ -231,42 +272,57 @@
Heart beat from a service.
+Definition
+""""""""""
+
**URL path:**
- /services/keepalive?name=<service-name>
+
+/services/keepalive?name=<service-name>
**Parameters:**
- name: (*Required*)
- The name of the service.
+
+name: (*Required*)
+
+The name of the service.
**Responses:**
- 200:
- OK
- 404:
- Service is not found.
-**Examples:**
- **Call**: ::
+200:
- curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
+OK
- Result:
- 200: ::
+404:
- OK
+Service is not found.
- **Call**: ::
+Examples
+""""""""
- curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
+**Call**: ::
- Result:
- 404: ::
+ curl -X PUT "http://localhost:8081/services/keepalive?name=existing"
- Could not find service: nonexistent
+**Result**:
+
+200: ::
+
+ OK
+
+**Call**: ::
+
+ curl -X PUT "http://localhost:8081/services/keepalive?name=nonexistent"
+
+**Result**:
+
+404: ::
+
+ Could not find service: nonexistent
.. _policy-management:
-Policy Management
-=================
+************
+Policy Types
+************
Policies are based on types. The set of available policy types is determined by the set of policy types supported by
Near |nbh| RT |nbsp| RICs. At startup, the Policy Agent queries all Near |nbh| RT |nbsp| RICs for their supported types
@@ -274,20 +330,6 @@
to date. Policy types cannot be created, updated or deleted using this interface since this must be done via the
Near |nbh| RT |nbsp| RICs.
-Policies can be queried, created, updated, and deleted. A policy is always created in a specific
-Near |nbh| RT |nbsp| RIC.
-
-When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
-it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
-inconsistency, the Policy Agent will start a synchronization job and try to reflect the status of the
-Near |nbh| RT |nbsp| RIC. If this fails, the Policy Agent will delete all policies for the specific
-Near |nbh| RT |nbsp| RIC in the internal repository and set its state to *UNKNOWN*. This means that no interaction with
-the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent has been able to contact it again and re-synchronize its
-state in the repository.
-
-Policy Types
-------------
-
A policy type defines a name and a JSON schema that constrains the content of a policy of that type.
/policy_types
@@ -298,42 +340,55 @@
Query policy type names.
+Definition
+""""""""""
+
**URL path:**
- /policy_types?ric=<name-of-ric>
+
+/policy_types?ric=<name-of-ric>
**Parameters:**
- ric: (*Optional*)
- The name of the Near |nbh| RT |nbsp| RIC to get types for.
+
+ric: (*Optional*)
+
+The name of the Near |nbh| RT |nbsp| RIC to get types for.
**Responses:**
- 200:
- Array of policy type names.
- 404:
- Near |nbh| RT |nbsp| RIC is not found.
+200:
-**Examples:**
- **Call**: ::
+ Array of policy type names.
- curl -X GET "http://localhost:8081/policy_types"
+404:
- Result:
- 200: ::
+ Near |nbh| RT |nbsp| RIC is not found.
- [
- "STD_PolicyModelUnconstrained_0.2.0",
- "Example_QoETarget_1.0.0",
- "ERIC_QoSNudging_0.2.0"
- ]
+Examples
+""""""""
- **Call**: ::
+**Call**: ::
- curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
+ curl -X GET "http://localhost:8081/policy_types"
- Result:
- 404: ::
+**Result**:
- org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
+200: ::
+
+ [
+ "STD_PolicyModelUnconstrained_0.2.0",
+ "Example_QoETarget_1.0.0",
+ "ERIC_QoSNudging_0.2.0"
+ ]
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policy_types?ric=nonexistent"
+
+**Result**:
+
+404: ::
+
+ org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
/policy_schema
~~~~~~~~~~~~~~
@@ -343,81 +398,95 @@
Returns one policy type schema definition.
+Definition
+""""""""""
+
**URL path:**
- /policy_schema?id=<name-of-type>
+
+/policy_schema?id=<name-of-type>
**Parameters:**
- id: (*Required*)
- The ID of the policy type to get the definition for.
+
+id: (*Required*)
+
+The ID of the policy type to get the definition for.
**Responses:**
- 200:
- Policy schema as JSON schema.
- 404:
- Policy type is not found.
-**Examples:**
- **Call**: ::
+200:
- curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
+Policy schema as JSON schema.
- Result:
- 200: ::
+404:
- {
- "$schema": "http://json-schema.org/draft-07/schema#",
- "title": "STD_PolicyModelUnconstrained_0.2.0",
- "description": "Standard model of a policy with unconstrained scope id combinations",
+Policy type is not found.
+
+Examples
+""""""""
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policy_schema?id=STD_PolicyModelUnconstrained_0.2.0"
+
+**Result**:
+
+200: ::
+
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "STD_PolicyModelUnconstrained_0.2.0",
+ "description": "Standard model of a policy with unconstrained scope id combinations",
+ "type": "object",
+ "properties": {
+ "scope": {
"type": "object",
"properties": {
- "scope": {
- "type": "object",
- "properties": {
- "ueId": {"type": "string"},
- "groupId": {"type": "string"}
- },
- "minProperties": 1,
- "additionalProperties": false
- },
- "qosObjectives": {
- "type": "object",
- "properties": {
- "gfbr": {"type": "number"},
- "mfbr": {"type": "number"}
- },
- "additionalProperties": false
- },
- "resources": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "cellIdList": {
- "type": "array",
- "minItems": 1,
- "uniqueItems": true,
- "items": {
- "type": "string"
- }
- },
- "additionalProperties": false,
- "required": ["cellIdList"]
- }
- }
+ "ueId": {"type": "string"},
+ "groupId": {"type": "string"}
},
"minProperties": 1,
- "additionalProperties": false,
- "required": ["scope"]
+ "additionalProperties": false
+ },
+ "qosObjectives": {
+ "type": "object",
+ "properties": {
+ "gfbr": {"type": "number"},
+ "mfbr": {"type": "number"}
+ },
+ "additionalProperties": false
+ },
+ "resources": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "cellIdList": {
+ "type": "array",
+ "minItems": 1,
+ "uniqueItems": true,
+ "items": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false,
+ "required": ["cellIdList"]
+ }
}
+ },
+ "minProperties": 1,
+ "additionalProperties": false,
+ "required": ["scope"]
+ }
- **Call**: ::
+**Call**: ::
- curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
+ curl -X GET "http://localhost:8081/policy_schema?id=nonexistent"
- Result:
- 404: ::
+**Result**:
- org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
+404: ::
+
+ org.oransc.policyagent.exceptions.ServiceException: Could not find type: nonexistent
/policy_schemas
~~~~~~~~~~~~~~~
@@ -427,70 +496,102 @@
Returns policy type schema definitions.
+Definition
+""""""""""
+
**URL path:**
- /policy_schemas?ric=<name-of-ric>
+
+/policy_schemas?ric=<name-of-ric>
**Parameters:**
- ric: (*Optional*)
- The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
+
+ric: (*Optional*)
+
+The name of the Near |nbh| RT |nbsp| RIC to get the definitions for.
**Responses:**
- 200:
- An array of policy schemas as JSON schemas.
- 404:
- Near |nbh| RT |nbsp| RIC is not found.
-**Examples:**
- **Call**: ::
+200:
- curl -X GET "http://localhost:8081/policy_schemas"
+An array of policy schemas as JSON schemas.
- Result:
- 200: ::
+404:
- [{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "title": "STD_PolicyModelUnconstrained_0.2.0",
- "description": "Standard model of a policy with unconstrained scope id combinations",
- "type": "object",
- "properties": {
- "scope": {
- "type": "object",
+Near |nbh| RT |nbsp| RIC is not found.
+
+Examples
+""""""""
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policy_schemas"
+
+**Result**:
+
+200: ::
+
+ [
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "STD_PolicyModelUnconstrained_0.2.0",
+ "description": "Standard model of a policy with unconstrained scope id combinations",
+ "type": "object",
+ "properties": {
+ "scope": {
+ "type": "object",
.
.
.
+ }
"additionalProperties": false,
"required": ["scope"]
},
- .
- .
- .
+ .
+ .
+ .
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Example_QoETarget_1.0.0",
"description": "Example QoE Target policy type",
"type": "object",
- "properties": {
- "scope": {
- "type": "object",
- .
- .
- .
- "additionalProperties": false,
- "required": ["scope"]
- }]
+ "properties": {
+ "scope": {
+ "type": "object",
+ .
+ .
+ .
+ }
+ "additionalProperties": false,
+ "required": ["scope"]
+ }
+ }
+ }
+ ]
- **Call**: ::
+**Call**: ::
- curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
+ curl -X GET "http://localhost:8081/policy_schemas?ric=nonexistent"
- Result:
- 404: ::
+**Result**:
- org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
+404: ::
-Policy
-------
+ org.oransc.policyagent.exceptions.ServiceException: Could not find ric: nonexistent
+
+*****************
+Policy Management
+*****************
+
+Policies can be queried, created, updated, and deleted. A policy is always created in a specific
+Near |nbh| RT |nbsp| RIC.
+
+When a policy is created, the Policy Agent stores information about it in its internal repository. At regular intervals,
+it then checks with all Near |nbh| RT |nbsp| RICs that this repository is synchronized. If, for some reason, there is an
+inconsistency, the Policy Agent will start a synchronization job and try to reflect the status of the
+Near |nbh| RT |nbsp| RIC. If this fails, the Policy Agent will delete all policies for the specific
+Near |nbh| RT |nbsp| RIC in the internal repository and set its state to *UNKNOWN*. This means that no interaction with
+the Near |nbh| RT |nbsp| RIC is possible until the Policy Agent has been able to contact it again and re-synchronize its
+state in the repository.
A policy is defined by its type schema.
@@ -512,81 +613,98 @@
Query policies.
+Definition
+""""""""""
+
**URL path:**
- /policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
+
+/policies?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-type>
**Parameters:**
- ric: (*Optional*)
- The name of the Near |nbh| RT |nbsp| RIC to get policies for.
- service: (*Optional*)
- The name of the service to get policies for.
- type: (*Optional*)
- The name of the policy type to get policies for.
+
+ric: (*Optional*)
+
+The name of the Near |nbh| RT |nbsp| RIC to get policies for.
+
+service: (*Optional*)
+
+The name of the service to get policies for.
+
+type: (*Optional*)
+
+The name of the policy type to get policies for.
**Responses:**
- 200:
- Array of JSON objects (PolicyInfo). ::
- {
- "id": "string", (Identity of the policy)
- "json": "object", (The configuration of the policy)
- "lastModified": "string", (Timestamp, last modification time)
- "ric": "string", (Identity of the target Near |nbh| RT |nbsp| RIC)
- "service": "string", (The name of the service owning the policy)
- "type": "string" (Name of the policy type)
- }
- 404:
- Near |nbh| RT |nbsp| RIC or policy type not found.
+200:
-**Examples:**
- **Call**: ::
+Array of JSON objects (PolicyInfo). ::
- curl -X GET "http://localhost:8081/policies?ric=existing"
+ {
+ "id": "string", (Identity of the policy)
+ "json": "object", (The configuration of the policy)
+ "lastModified": "string", (Timestamp, last modification time)
+ "ric": "string", (Identity of the target Near |nbh| RT |nbsp| RIC)
+ "service": "string", (The name of the service owning the policy)
+ "type": "string" (Name of the policy type)
+ }
- Result:
- 200: ::
+404:
+ Near |nbh| RT |nbsp| RIC or policy type not found.
- [
- {
- "id": "Policy 1",
- "json": {
- "scope": {
- "ueId": "UE 1",
- "groupId": "Group 1"
- },
- "qosObjectives": {
- "gfbr": 1,
- "mfbr": 2
- },
- "cellId": "Cell 1"
- },
- "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
- "ric": "existing",
- "service": "Service 1",
- "type": "STD_PolicyModelUnconstrained_0.2.0"
- },
- {
- "id": "Policy 2",
- "json": {
- .
- .
- .
- },
- "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
- "ric": "existing",
- "service": "Service 2",
- "type": "Example_QoETarget_1.0.0"
- }
- ]
+Examples
+""""""""
- **Call**: ::
+**Call**: ::
- curl -X GET "http://localhost:8081/policies?type=nonexistent"
+ curl -X GET "http://localhost:8081/policies?ric=existing"
- Result:
- 404: ::
+**Result**:
- Policy type not found
+200: ::
+
+ [
+ {
+ "id": "Policy 1",
+ "json": {
+ "scope": {
+ "ueId": "UE 1",
+ "groupId": "Group 1"
+ },
+ "qosObjectives": {
+ "gfbr": 1,
+ "mfbr": 2
+ },
+ "cellId": "Cell 1"
+ },
+ "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
+ "ric": "existing",
+ "service": "Service 1",
+ "type": "STD_PolicyModelUnconstrained_0.2.0"
+ },
+ {
+ "id": "Policy 2",
+ "json": {
+ .
+ .
+ .
+ },
+ "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT",
+ "ric": "existing",
+ "service": "Service 2",
+ "type": "Example_QoETarget_1.0.0"
+ }
+ ]
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policies?type=nonexistent"
+
+**Result**:
+
+404: ::
+
+ Policy type not found
/policy
~~~~~~~
@@ -596,71 +714,85 @@
Returns a policy configuration.
+Definition
+""""""""""
+
**URL path:**
- /policy?id=<policy-id>
+
+/policy?id=<policy-id>
**Parameters:**
- id: (*Required*)
- The ID of the policy instance.
+
+id: (*Required*)
+
+The ID of the policy instance.
**Responses:**
- 200:
- JSON object containing policy information. ::
- {
- "id": "string", (ID of policy)
- "json": "object", (JSON with policy data speified by the type)
- "ownerServiceName": "string", (Name of the service that created the policy)
- "ric": "string", (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
- "type": "string", (Name of the policy type of the policy)
- "lastModified" (Timestamp, last modification time)
- }
- 404:
- Policy is not found.
+200:
-**Examples:**
- **Call**: ::
+JSON object containing policy information. ::
- curl -X GET "http://localhost:8081/policy?id=Policy 1"
+ {
+ "id": "string", (ID of policy)
+ "json": "object", (JSON with policy data speified by the type)
+ "ownerServiceName": "string", (Name of the service that created the policy)
+ "ric": "string", (Name of the Near |nbh| RT |nbsp| RIC where the policy resides)
+ "type": "string", (Name of the policy type of the policy)
+ "lastModified" (Timestamp, last modification time)
+ }
- Result:
- 200: ::
+404:
- {
- "id": "Policy 1",
- "json", {
- "scope": {
- "ueId": "UE1 ",
- "cellId": "Cell 1"
- },
- "qosObjectives": {
- "gfbr": 319.5,
- "mfbr": 782.75,
- "priorityLevel": 268.5,
- "pdb": 44.0
- },
- "qoeObjectives": {
- "qoeScore": 329.0,
- "initialBuffering": 27.75,
- "reBuffFreq": 539.0,
- "stallRatio": 343.0
- },
- "resources": []
- },
- "ownerServiceName": "Service 1",
- "ric": "ric1",
- "type": "STD_PolicyModelUnconstrained_0.2.0",
- "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
- }
+Policy is not found.
- **Call**: ::
+Examples
+""""""""
- curl -X GET "http://localhost:8081/policy?id=nonexistent"
+**Call**: ::
- Result:
- 404: ::
+ curl -X GET "http://localhost:8081/policy?id=Policy 1"
- Policy is not found
+**Result**:
+
+200: ::
+
+ {
+ "id": "Policy 1",
+ "json", {
+ "scope": {
+ "ueId": "UE1 ",
+ "cellId": "Cell 1"
+ },
+ "qosObjectives": {
+ "gfbr": 319.5,
+ "mfbr": 782.75,
+ "priorityLevel": 268.5,
+ "pdb": 44.0
+ },
+ "qoeObjectives": {
+ "qoeScore": 329.0,
+ "initialBuffering": 27.75,
+ "reBuffFreq": 539.0,
+ "stallRatio": 343.0
+ },
+ "resources": []
+ },
+ "ownerServiceName": "Service 1",
+ "ric": "ric1",
+ "type": "STD_PolicyModelUnconstrained_0.2.0",
+ "lastModified": "Wed, 01 Apr 2020 07:45:45 GMT"
+ }
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policy?id=nonexistent"
+
+**Result**:
+
+404: ::
+
+ Policy is not found
PUT
+++
@@ -668,59 +800,83 @@
Create/Update a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
"*Keep Alive Interval*" registered.
+Definition
+""""""""""
+
**URL path:**
- /policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
+
+/policy?id=<policy-id>&ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
**Parameters:**
- id: (*Required*)
- The ID of the policy instance.
- ric: (*Required*)
- The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
- service: (*Required*)
- The name of the service creating the policy.
- type: (*Optional*)
- The name of the policy type.
+
+id: (*Required*)
+
+The ID of the policy instance.
+
+ric: (*Required*)
+
+The name of the Near |nbh| RT |nbsp| RIC where the policy will be created.
+
+service: (*Required*)
+
+The name of the service creating the policy.
+
+type: (*Optional*)
+
+The name of the policy type.
**Body:** (*Required*)
- A JSON object containing the data specified by the type.
+
+A JSON object containing the data specified by the type.
**Responses:**
- 200:
- Policy updated.
- 201:
- Policy created.
- 404:
- Near |nbh| RT |nbsp| RIC or policy type is not found.
- 423:
- Near |nbh| RT |nbsp| RIC is not operational.
-**Examples:**
- **Call**: ::
+200:
- curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
- -H "Content-Type: application/json"
- -d '{
- "scope": {
- "ueId": "UE 1",
- "cellId": "Cell 1"
- },
- "qosObjectives": {
- "gfbr": 319.5,
- "mfbr": 782.75,
- "priorityLevel": 268.5,
- "pdb": 44.0
- },
- "qoeObjectives": {
- "qoeScore": 329.0,
- "initialBuffering": 27.75,
- "reBuffFreq": 539.0,
- "stallRatio": 343.0
- },
- "resources": []
- }'
+Policy updated.
- Result:
- 200
+201:
+
+Policy created.
+
+404:
+
+Near |nbh| RT |nbsp| RIC or policy type is not found.
+
+423:
+
+Near |nbh| RT |nbsp| RIC is not operational.
+
+Examples
+""""""""
+
+**Call**: ::
+
+ curl -X PUT "http://localhost:8081/policy?id=Policy%201&ric=ric1&service=Service%201&type=STD_PolicyModelUnconstrained_0.2.0"
+ -H "Content-Type: application/json"
+ -d '{
+ "scope": {
+ "ueId": "UE 1",
+ "cellId": "Cell 1"
+ },
+ "qosObjectives": {
+ "gfbr": 319.5,
+ "mfbr": 782.75,
+ "priorityLevel": 268.5,
+ "pdb": 44.0
+ },
+ "qoeObjectives": {
+ "qoeScore": 329.0,
+ "initialBuffering": 27.75,
+ "reBuffFreq": 539.0,
+ "stallRatio": 343.0
+ },
+ "resources": []
+ }'
+
+**Result**:
+
+200
DELETE
++++++
@@ -728,28 +884,43 @@
Deletes a policy. **Note!** Calls to this method will also trigger "*Keep Alive*" for a service which has a
"*Keep Alive Interval*" registered.
+Definition
+""""""""""
+
**URL path:**
- /policy?id=<policy-id>
+
+/policy?id=<policy-id>
**Parameters:**
- id: (*Required*)
- The ID of the policy instance.
+
+id: (*Required*)
+
+The ID of the policy instance.
**Responses:**
- 204:
- Policy deleted.
- 404:
- Policy is not found.
- 423:
- Near |nbh| RT |nbsp| RIC is not operational.
-**Examples:**
- **Call**: ::
+204:
- curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
+Policy deleted.
- Result:
- 204
+404:
+
+Policy is not found.
+
+423:
+
+Near |nbh| RT |nbsp| RIC is not operational.
+
+Examples
+""""""""
+
+**Call**: ::
+
+ curl -X DELETE "http://localhost:8081/policy?id=Policy 1"
+
+**Result**:
+
+204
/policy_ids
~~~~~~~~~~~
@@ -759,45 +930,63 @@
Query policy type IDs.
+Definition
+""""""""""
+
**URL path:**
- /policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
+
+/policy_ids?ric=<name-of-ric>&service=<name-of-service>&type=<name-of-policy-type>
**Parameters:**
- ric: (*Optional*)
- The name of the Near |nbh| RT |nbsp| RIC to get policies for.
- service: (*Optional*)
- The name of the service to get policies for.
- type: (*Optional*)
- The name of the policy type to get policies for.
+
+ric: (*Optional*)
+
+The name of the Near |nbh| RT |nbsp| RIC to get policies for.
+
+service: (*Optional*)
+
+The name of the service to get policies for.
+
+type: (*Optional*)
+
+The name of the policy type to get policies for.
**Responses:**
- 200:
- Array of policy type names.
- 404:
- RIC or policy type not found.
-**Examples:**
- **Call**: ::
+200:
- curl -X GET "http://localhost:8081/policy_ids"
+Array of policy type names.
- Result:
- 200: ::
+404:
- [
- "Policy 1",
- "Policy 2",
- "Policy 3"
- ]
+RIC or policy type not found.
- **Call**: ::
+Examples
+""""""""
- curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
+**Call**: ::
- Result:
- 404: ::
+ curl -X GET "http://localhost:8081/policy_ids"
- Ric not found
+**Result**:
+
+200: ::
+
+ [
+ "Policy 1",
+ "Policy 2",
+ "Policy 3"
+ ]
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/policy_ids?ric=nonexistent"
+
+**Result**:
+
+404: ::
+
+ Ric not found
/policy_status
~~~~~~~~~~~~~~
@@ -807,29 +996,37 @@
Returns the status of a policy.
+Definition
+""""""""""
+
**URL path:**
- /policy_status?id=<policy-id>
+
+/policy_status?id=<policy-id>
**Parameters:**
- id: (*Required*)
- The ID of the policy.
+
+id: (*Required*)
+
+The ID of the policy.
**Responses:**
- 200:
- JSON object with policy status.
- 404:
- Policy not found.
+200:
+
+JSON object with policy status.
+
+404:
+
+Policy not found.
+
+**********************
Near-RT RIC Repository
-======================
+**********************
The Policy Agent keeps an updated view of the Near |nbh| RT |nbsp| RICs that are available in the system. A service can
find out which Near |nbh| RT |nbsp| RIC that manages a specific element in the network or which
Near |nbh| RT |nbsp| RICs that support a specific policy type.
-Near-RT RIC
------------
-
/ric
~~~~
@@ -838,35 +1035,49 @@
Returns the name of a Near |nbh| RT |nbsp| RIC managing a specific Mananged Element.
- **URL path:**
- /ric?managedElementId=<id-of-managed-element>
+Definition
+""""""""""
+
+**URL path:**
+
+/ric?managedElementId=<id-of-managed-element>
**Parameters:**
- managedElementId: (*Required*)
- The ID of the Managed Element.
+
+managedElementId: (*Required*)
+
+The ID of the Managed Element.
**Responses:**
- 200:
- Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
- 404:
- No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
-**Examples:**
- **Call**: ::
+200:
- curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
+Name of the Near |nbh| RT |nbsp| RIC managing the Managed Element.
- Result:
- 200: ::
+404:
- Ric 1
+No Near |nbh| RT |nbsp| RIC manages the given Managed Element.
- **Call**: ::
+Examples
+""""""""
- curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
+**Call**: ::
- Result:
- 404
+ curl -X GET "http://localhost:8081/ric?managedElementId=Node 1"
+
+**Result**:
+
+200: ::
+
+ Ric 1
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/ric?managedElementId=notmanaged"
+
+**Result**:
+
+404
/rics
~~~~~
@@ -876,86 +1087,98 @@
Query Near |nbh| RT |nbsp| RIC information.
- **URL path:**
- /rics?policyType=<name-of-policy-type>
+Definition
+""""""""""
+
+**URL path:**
+
+/rics?policyType=<name-of-policy-type>
**Parameters:**
- policyType: (*Optional*)
- The name of the policy type.
+
+policyType: (*Optional*)
+
+The name of the policy type.
**Responses:**
- 200:
- Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
- [
- {
- "managedElementIds": [
- "string"
- ],
- "policyTypes": [
- "string"
- ],
- "ricName": "string",
- "state": "string"
- }
- ]
- 404:
- Policy type is not found.
+200:
-**Examples:**
- **Call**: ::
+Array of JSON objects containing Near |nbh| RT |nbsp| RIC information. ::
- curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
+ [
+ {
+ "managedElementIds": [
+ "string"
+ ],
+ "policyTypes": [
+ "string"
+ ],
+ "ricName": "string",
+ "state": "string"
+ }
+ ]
- Result:
- 200: ::
+404:
- [
- {
- "managedElementIds": [
- "ME 1",
- "ME 2"
- ],
- "policyTypes": [
- "STD_PolicyModelUnconstrained_0.2.0",
- "Example_QoETarget_1.0.0",
- "ERIC_QoSNudging_0.2.0"
- ],
- "ricName": "Ric 1",
- "state": "AVAILABLE"
- },
- .
- .
- .
- {
- "managedElementIds": [
- "ME 3"
- ],
- "policyTypes": [
- "STD_PolicyModelUnconstrained_0.2.0"
- ],
- "ricName": "Ric X",
- "state": "UNAVAILABLE"
- }
- ]
+Policy type is not found.
- **Call**: ::
+Examples
+""""""""
- curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
+**Call**: ::
- Result:
- 404: ::
+ curl -X GET "http://localhost:8081/rics?policyType=STD_PolicyModelUnconstrained_0.2.0"
- Policy type not found
+**Result**:
+200: ::
+
+ [
+ {
+ "managedElementIds": [
+ "ME 1",
+ "ME 2"
+ ],
+ "policyTypes": [
+ "STD_PolicyModelUnconstrained_0.2.0",
+ "Example_QoETarget_1.0.0",
+ "ERIC_QoSNudging_0.2.0"
+ ],
+ "ricName": "Ric 1",
+ "state": "AVAILABLE"
+ },
+ .
+ .
+ .
+ {
+ "managedElementIds": [
+ "ME 3"
+ ],
+ "policyTypes": [
+ "STD_PolicyModelUnconstrained_0.2.0"
+ ],
+ "ricName": "Ric X",
+ "state": "UNAVAILABLE"
+ }
+ ]
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/rics?policyType=nonexistent"
+
+**Result**:
+
+404: ::
+
+ Policy type not found
+
+************
Health Check
-============
+************
The status of the Policy Agent.
-Health Check
-------------
-
/status
~~~~~~~
@@ -964,23 +1187,33 @@
Returns the status of the Policy Agent.
- **URL path:**
- /status
+Definition
+""""""""""
+
+**URL path:**
+
+/status
**Parameters:**
- None.
+
+None.
**Responses:**
- 200:
- Service is living.
-**Examples:**
- **Call**: ::
+200:
- curl -X GET "http://localhost:8081/status"
+Service is living.
- Result:
- 200
+Examples
+""""""""
+
+**Call**: ::
+
+ curl -X GET "http://localhost:8081/status"
+
+**Result**:
+
+200
****************
A1 through DMaaP
@@ -991,7 +1224,7 @@
published back to the DMaaP Message Router with the result of the call.
Send Message
-============
+~~~~~~~~~~~~
The message to send is a JSON like the one below. The "*url*" is one of the URLs described under
:ref:`policy-management`. The "*target*" must always be "*policy-agent*" for the message to be processed by the Policy
@@ -1010,7 +1243,7 @@
}
Example
--------
++++++++
To get all policy types for a specific Near |nbh| RT |nbsp| RIC the following message should be sent to DMaaP Message
Router: ::
@@ -1028,7 +1261,7 @@
}
Receive Message
-===============
+~~~~~~~~~~~~~~~
The message the Policy Agent sends back to the DMaaP Message Router is a JSON like the one below. The "*requestId*"
"*correlationId*", and "*originatorId*" are the same as in the message sent to DMaaP MR. ::
@@ -1039,13 +1272,13 @@
"originatorId": "string",
"type": "string",
"message": "string",
- "type": string",
+ "type": "string",
"timestamp": "string",
"status": "string"
}
Example
--------
++++++++
The response containing all policy types for a specific Near |nbh| RT |nbsp| RIC sent to the DMaaP Message Router from
the Policy Agent: ::