Update Policy Offered APIs

[policy/parent.git] / docs / api / api.rst

diff --git a/docs/api/api.rst b/docs/api/api.rst
index c65e35e..17df746 100644 (file)
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -8,6 +8,12 @@
 Policy Life Cycle API
 #####################
 
 Policy Life Cycle API
 #####################
 

+1. Policy Life Cycle API
+========================
+
+1.1 Overview
+------------
+

 .. contents::
     :depth: 2
 
 .. contents::
     :depth: 2
 


@@ -29,7 +35,7 @@ One Service Template can contain multiple policies and policy types.
 
 Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy
 Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy.
 
 Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy
 Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy.

-See also `the examples in Github <hhttps://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`_.
+See also `the examples in Github <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`_.

 
 ::
 
 
 ::
 


@@ -105,6 +111,8 @@ triggers     R       O        N/A        Specification of policy triggers, not c
   The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
   equivalent to the Policy Enforcement Point (PEP) concept
 
   The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
   equivalent to the Policy Enforcement Point (PEP) concept
 

+1.2 Preloaded policy types and policies
+---------------------------------------

 
 To ease policy creation, we preload several widely used policy types in policy database. Below is a table listing the preloaded policy types.
 
 
 To ease policy creation, we preload several widely used policy types in policy database. Below is a table listing the preloaded policy types.
 


@@ -114,7 +122,7 @@ To ease policy creation, we preload several widely used policy types in policy d
    :header: "Policy Type Name", "Payload"
    :widths: 15,10
 
    :header: "Policy Type Name", "Payload"
    :widths: 15,10
 

-   "Monitoring.TCA", `onap.policies.monitoring.cdap.tca.hi.lo.app.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app.yaml>`_
+   "Monitoring.TCA", `onap.policies.monitoring.tcagen2.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.tcagen2.yaml>`_

    "Monitoring.Collectors", `onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml>`_
    "Optimization", `onap.policies.Optimization.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_
    "Optimization.Resource", `onap.policies.optimization.Resource.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
    "Monitoring.Collectors", `onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml>`_
    "Optimization", `onap.policies.Optimization.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_
    "Optimization.Resource", `onap.policies.optimization.Resource.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_


@@ -132,8 +140,8 @@ To ease policy creation, we preload several widely used policy types in policy d
    "Controlloop.Guard.Common.Blacklist", `onap.policies.controlloop.guard.common.Blacklist.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
    "Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`_
    "Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`_
    "Controlloop.Guard.Common.Blacklist", `onap.policies.controlloop.guard.common.Blacklist.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
    "Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`_
    "Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`_

+   "Controlloop.Guard.Common.Filter", `onap.policies.controlloop.guard.common.Filter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`_

    "Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml>`_
    "Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml>`_

-   "Controlloop.Operational", `onap.policies.controlloop.Operational.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.Operational.yaml>`_

    "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.Common.yaml>`_
    "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml>`_
    "Controlloop.Operational.Common.Drools", `onap.policies.controlloop.operational.common.Drools.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`_
    "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.Common.yaml>`_
    "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml>`_
    "Controlloop.Operational.Common.Drools", `onap.policies.controlloop.operational.common.Drools.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`_


@@ -169,24 +177,25 @@ Below is a table containing sample well-formed TOSCA compliant policies.
    "vFirewallCDS.Operational.Tosca", `vFirewallCDS.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewallCDS.policy.operational.input.tosca.yaml>`_
 
 
    "vFirewallCDS.Operational.Tosca", `vFirewallCDS.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewallCDS.policy.operational.input.tosca.yaml>`_
 
 

-Below is a global API table from where swagger JSON for different types of policy design API can be downloaded.
+2. APIs exposed
+===============
+
+2.1 Global API Table
+--------------------
+
+Below you can download the swagger YAML for Policy Framework Lifecycle API.
+You can find *Tosca Node Template Design* and *Policy Design* operations.

 
 

-Global API Table
-----------------

 .. csv-table::
 .. csv-table::

-   :header: "API name", "Swagger JSON"
+   :header: "API name", "Swagger YAML"

    :widths: 10,5
 
    :widths: 10,5
 

-   "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`"
-   "Statistics API", ":download:`link <swagger/statistics-api.json>`"
-   "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`"
-   "Tosca Policy API", ":download:`link <swagger/policy-api.json>`"
-   "Legacy Operational Policy API", ":download:`link <swagger/operational-policy-api.json>`"
+   "Policy Framework Lifecycle API", ":download:`link <https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml>`"

 
 

-API Swagger
------------
+2.2 API Swagger
+---------------

 
 

-It is worth noting that we use basic authorization for API access with username and password set to *healthcheck* and *zb!XztG34* respectively.
+It is worth noting that we use basic authorization for API access with username and password set to *policyadmin* and *zb!XztG34* respectively.

 Also, the new APIs support both *http* and *https*.
 
 For every API call, client is encouraged to insert an uuid-type requestID as parameter.
 Also, the new APIs support both *http* and *https*.
 
 For every API call, client is encouraged to insert an uuid-type requestID as parameter.


@@ -210,13 +219,50 @@ x-patchversion is used only to communicate a PATCH version in a response for tro
 
 x-onap-requestid is used to track REST transactions for logging purpose, as described above.
 
 
 x-onap-requestid is used to track REST transactions for logging purpose, as described above.
 

-.. swaggerv2doc:: swagger/healthcheck-api.json

 
 

-.. swaggerv2doc:: swagger/statistics-api.json
+.. csv-table::
+   :header: "SWAGGER"
+   :widths: 10
+
+   `To view the full SWAGGER click here <./local-swagger.html>`_
+    
+.. note::
+   Note that the context-path is not present in the document, because it is in the `application.yaml <https://github.com/onap/policy-api/blob/master/main/src/main/resources/application.yaml>`_ 
+   So the final url is composed by:
+   
+   .. csv-table::
+       :header: "Scheme","Host","Context-Path","Path"
+       :widths: 3,3,3,3
+    
+       "http","://<IP>:<PORT>","/policy/api/v1/","healthcheck"
+
+
+2.3 Creating MetadataSet for policy
+-----------------------------------
+
+The policy type implementation in tosca policy can be independently persisted to the database as metadataSets via the Tosca node template Apis .
+The policy type implementation data can be excluded from the policy properties section of the tosca policy and the user can specify only the "metadataSetName" and "metadataSetVersion"
+fields under the policy "metadata" section to map a specific policy type implementation to the policy during the policy creation.
+
+The following sample tosca service template comprises a list of tosca node templates each containing a policy type implementation data in the form of metadataSet that can be persisted to the database independently using the policy node template Api.
+
+.. csv-table::
+   :header: "Tosca node template", "Payload"
+   :widths: 15,10
+
+   "sample.nodetemplates.metadatasets", `nodetemplates.metadatasets.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/nodetemplates/nodetemplates.metadatasets.input.tosca.yaml>`_  `nodetemplates.metadatasets.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/nodetemplates/nodetemplates.metadatasets.input.tosca.json>`_
+

 
 

-.. swaggerv2doc:: swagger/policytype-api.json
+The following sample tosca policy shows the policy metadata section that maps to one of the metadataSets stored in the database prior to the policy creation.

 
 

-.. swaggerv2doc:: swagger/policy-api.json
+.. csv-table::
+   :header: "Tosca policy", "Payload"
+   :widths: 15,10
+
+   "apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/apex.policy.decisionmaker.input.tosca.yaml>`_
+
+`The node template Apis <./local-swagger.html#tag/Tosca-Node-Template-Design>`_ 
+are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.

 
 When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
 but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA
 
 When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
 but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA


@@ -256,14 +302,12 @@ To be specific, the following rules are implemented to enforce the version:
    also includes "policy-id": "sample-policy-name2" and "policy-version": "2.0.0". The 200 return of this POST call will have this created policy with
    metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0".
 
    also includes "policy-id": "sample-policy-name2" and "policy-version": "2.0.0". The 200 return of this POST call will have this created policy with
    metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0".
 

-.. swaggerv2doc:: swagger/operational-policy-api.json
-

 Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy
 or policy type at a time for safety purpose. If client has the need to delete multiple or a group of policies or policy types,
 they will need to delete them one by one.
 
 Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy
 or policy type at a time for safety purpose. If client has the need to delete multiple or a group of policies or policy types,
 they will need to delete them one by one.
 

-Sample API Curl Commands
--------------------------
+2.4 Sample API Curl Commands
+----------------------------

 
 From an API client perspective, using *http* or *https* does not make much difference to the curl command.
 Here we list some sample curl commands (using *http*) for POST, GET and DELETE monitoring and operational policies that are used in vFirewall use case.
 
 From an API client perspective, using *http* or *https* does not make much difference to the curl command.
 Here we list some sample curl commands (using *http*) for POST, GET and DELETE monitoring and operational policies that are used in vFirewall use case.


@@ -272,19 +316,36 @@ JSON payload for POST calls can be downloaded from policy table above.
 If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**.
 
 Create vFirewall Monitoring Policy::
 If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**.
 
 Create vFirewall Monitoring Policy::

-  curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.monitoring.input.tosca.json
+  curl --user 'policyadmin:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.monitoring.input.tosca.json

 
 Get vFirewall Monitoring Policy::
 
 Get vFirewall Monitoring Policy::

-  curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+  curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"

 
 Delete vFirewall Monitoring Policy::
 
 Delete vFirewall Monitoring Policy::

-  curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+  curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"

 
 Create vFirewall Operational Policy::
 
 Create vFirewall Operational Policy::

-  curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.operational.input.tosca.json
+  curl --user 'policyadmin:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.operational.input.tosca.json

 
 Get vFirewall Operational Policy::
 
 Get vFirewall Operational Policy::

-  curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+  curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"

 
 Delete vFirewall Operational Policy::
 
 Delete vFirewall Operational Policy::

-  curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+  curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+
+Get all available policies::
+  curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json"
+
+Get version 1.0.0 of vFirewall Monitoring Policy::
+  curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+
+Delete version 1.0.0 of vFirewall Monitoring Policy::
+  curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+
+
+3. Policy API application configuration
+=======================================
+
+Starting from Jakarta Release policy-api is a Springboot based microservice.
+
+The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://raw.githubusercontent.com/onap/oom/master/kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml>`_