Update Policy Offered APIs

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

diff --git a/docs/api/api.rst b/docs/api/api.rst
index 5aa3885..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
 


@@ -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.
 


@@ -169,22 +177,23 @@ 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>`"
-   "Tosca NodeTemplate API", ":download:`link <swagger/nodetemplates-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 *policyadmin* and *zb!XztG34* respectively.
 Also, the new APIs support both *http* and *https*.
 
 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*.


@@ -210,17 +219,26 @@ 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

 
 

-.. swaggerv2doc:: swagger/policytype-api.json
+.. csv-table::
+   :header: "SWAGGER"
+   :widths: 10

 
 

-.. swaggerv2doc:: swagger/policy-api.json
+   `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"

 
 
 
 

-Creating MetadataSet for policy
---------------------------------
+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"
 
 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"


@@ -243,9 +261,8 @@ The following sample tosca policy shows the policy metadata section that maps to
 
    "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>`_
 
 
    "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 following node template Apis are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
-
-.. swaggerv2doc:: swagger/nodetemplates-api.json
+`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


@@ -289,8 +306,8 @@ Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete
 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.
 
 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.


@@ -324,3 +341,11 @@ Get version 1.0.0 of vFirewall Monitoring Policy::
 
 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"
 
 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>`_