X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapi%2Fapi.rst;h=17df7463af73b8d61d3b310c5bdf666fdb68da57;hb=a43eb545dded63e1f21b7f14105ae0ed093b54db;hp=8b0ae3e8ae19f7a721e9456a0110c4bb60f8d692;hpb=5bc4f5ebe53508f29c21e583800904700fe03f87;p=policy%2Fparent.git diff --git a/docs/api/api.rst b/docs/api/api.rst index 8b0ae3e8..17df7463 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -8,6 +8,12 @@ Policy Life Cycle API ##################### +1. Policy Life Cycle API +======================== + +1.1 Overview +------------ + .. 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 +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. @@ -169,21 +177,23 @@ Below is a table containing sample well-formed TOSCA compliant policies. "vFirewallCDS.Operational.Tosca", `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:: - :header: "API name", "Swagger JSON" + :header: "API name", "Swagger YAML" :widths: 10,5 - "Healthcheck API", ":download:`link `" - "Statistics API", ":download:`link `" - "Tosca Policy Type API", ":download:`link `" - "Tosca Policy API", ":download:`link `" + "Policy Framework Lifecycle API", ":download:`link `" -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*. @@ -209,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. -.. 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 `_ + So the final url is composed by: + + .. csv-table:: + :header: "Scheme","Host","Context-Path","Path" + :widths: 3,3,3,3 + + "http","://:","/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 `_ `nodetemplates.metadatasets.input.tosca.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. + +.. csv-table:: + :header: "Tosca policy", "Payload" + :widths: 15,10 -.. swaggerv2doc:: swagger/policytype-api.json + "apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml `_ -.. swaggerv2doc:: swagger/policy-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 @@ -259,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. -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. @@ -294,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" + + +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 `_