blob: b9f3148279d69744e6e7e8a2b715d32115f1a5b7 [file] [log] [blame]
Chenfei Gao55e1f552019-05-21 13:32:30 -04001.. This work is licensed under a
2.. Creative Commons Attribution 4.0 International License.
3.. http://creativecommons.org/licenses/by/4.0
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04004
Pamela Dragosh9fcabd02020-05-13 07:54:15 -04005.. THIS IS USED INTERNALLY IN POLICY ONLY
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04006.. _api-label:
7
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -04008Policy Life Cycle API
Pamela Dragosh0ac4c6a2019-06-11 10:55:04 -04009#####################
Chenfei Gaof5f6d352019-08-23 15:50:58 -040010
11.. contents::
Chenfei Gao6d69ff92020-01-13 13:20:34 -050012 :depth: 2
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -040013
liamfallone83e6072020-05-06 13:09:09 +010014The purpose of this API is to support CRUD of TOSCA *PolicyType* and *Policy* entities. This API is provided by the
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040015*PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
liamfallone83e6072020-05-06 13:09:09 +010016<architecture-label>` page. The Policy design API backend is running in an independent building block component of the
17policy framework that provides REST services for the aforementioned CRUD behaviors. The Policy design API component interacts
18with a policy database for storing and fetching new policies or policy types as needed. Apart from CRUD, an API is also
19exposed for clients to retrieve healthcheck status of the API REST service and statistics report including a variety of
20counters that reflect the history of API invocation.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -040021
Chenfei Gao7984ada2020-03-17 22:34:15 -040022We strictly follow `TOSCA Specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`_
liamfallone83e6072020-05-06 13:09:09 +010023to define policy types and policies. A policy type defines the schema for a policy, expressing the properties, targets, and triggers
24that a policy may have. The type (string, int etc) and constraints (such as the range of legal values) of each property is defined
25in the Policy Type. Both Policy Type and policy are included in a TOSCA Service Template, which is used as the entity passed into an API
26POST call and the entity returned by API GET and DELETE calls. More details are presented in following sections. Policy Types and Policies
27can be composed for any given domain of application. All Policy Types and Policies must be composed as well-formed TOSCA Service Templates.
28One Service Template can contain multiple policies and policy types.
29
30Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy
31Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy.
Eric Debeau1d40bf62020-08-18 10:35:28 +020032See also `the examples in Github <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`_.
liamfallone83e6072020-05-06 13:09:09 +010033
34::
35
36 onap.policies.Optimization.yaml
37 onap.policies.optimization.Resource.yaml
38 onap.policies.optimization.resource.AffinityPolicy.yaml
39 onap.policies.optimization.resource.DistancePolicy.yaml
40 onap.policies.optimization.resource.HpaPolicy.yaml
41 onap.policies.optimization.resource.OptimizationPolicy.yaml
42 onap.policies.optimization.resource.PciPolicy.yaml
43 onap.policies.optimization.resource.Vim_fit.yaml
44 onap.policies.optimization.resource.VnfPolicy.yaml
45 onap.policies.optimization.Service.yaml
46 onap.policies.optimization.service.QueryPolicy.yaml
47 onap.policies.optimization.service.SubscriberPolicy.yaml
48
49Custom data types can be defined in TOSCA for properties specified in Policy Types. Data types can also inherit from parents, so a hierarchy of data types can also be built up.
50
51.. warning::
52 When creating a Policy Type, the ancestors of the Policy Type and all its custom Data Type definitions and ancestors MUST either already
53 exist in the database or MUST also be defined in the incoming TOSCA Service Template. Requests with missing or bad references are rejected
54 by the API.
55
56Each Policy Type can have multiple Policy instances created from it. Therefore, many Policy instances of the HpaPolicy Policy Type above can be created. When a policy is created, its Policy Type is specified in the *type* and *type_version* fields of the policy.
57
58.. warning::
59 The Policy Type specified for a Policy MUST exist in the database before the policy can be created. Requests with missing or bad
60 Policy Type references are rejected by the API.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -040061
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040062The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for
liamfallone83e6072020-05-06 13:09:09 +010063use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework.
64
65.. warning::
66 If a TOSCA entity (Data Type, Policy Type, or Policy with a certain version) already exists in the database and an attempt is made
67 to re-create the entity with different fields, the API will reject the request with the error message "entity in incoming fragment
68 does not equal existing entity". In such cases, delete the Policy or Policy Type and re-create it using the API.
69
70
71The TOSCA fields below are valid on API calls:
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040072
73============ ======= ======== ========== ===============================================================================
74**Field** **GET** **POST** **DELETE** **Comment**
75============ ======= ======== ========== ===============================================================================
76(name) M M M The definition of the reference to the Policy Type, GET allows ranges to be
77 specified
78version O M C GET allows ranges to be specified, must be specified if more than one version
liamfallone83e6072020-05-06 13:09:09 +010079 of the Policy Type exists and a specific version is required
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040080description R O N/A Desciption of the Policy Type
81derived_from R C N/A Must be specified when a Policy Type is derived from another Policy Type such
liamfallone83e6072020-05-06 13:09:09 +010082 as in the case of derived Monitoring Policy Types. The referenced Policy Type
83 must either already exist in the database or be defined as another policy type
84 in the incoming TOSCA service template
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040085metadata R O N/A Metadata for the Policy Type
liamfallone83e6072020-05-06 13:09:09 +010086properties R M N/A This field holds the specification of the specific Policy Type in ONAP. Any user
87 defined data types specified on properties must either already exist in the
88 database or be defined in the incoming TOSCA service template
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -040089targets R O N/A A list of node types and/or group types to which the Policy Type can be applied
90triggers R O N/A Specification of policy triggers, not currently supported in ONAP
91============ ======= ======== ========== ===============================================================================
92
93.. note::
94 On this and subsequent tables, use the following legend: M-Mandatory, O-Optional, R-Read-only, C-Conditional.
95 Conditional means the field is mandatory when some other field is present.
96
97.. note::
98 Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type
99 implementations is disabled.
100
101.. note::
liamfallone83e6072020-05-06 13:09:09 +0100102 Policy types that are in use (referenced by defined Policies and/or child policy types) may not be deleted.
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -0400103
104.. note::
105 The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
106 equivalent to the Policy Enforcement Point (PEP) concept
107
108
Chenfei Gao7984ada2020-03-17 22:34:15 -0400109To ease policy creation, we preload several widely used policy types in policy database. Below is a table listing the preloaded policy types.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400110
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -0400111.. _policy-preload-label:
112
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400113.. csv-table::
Chenfei Gao0a85b8b2019-09-10 22:22:17 -0400114 :header: "Policy Type Name", "Payload"
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400115 :widths: 15,10
116
Pamela Dragosh56316602020-08-20 09:16:20 -0400117 "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>`_
Chenfei Gaodfbc0ad2019-10-01 14:19:39 -0400118 "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>`_
119 "Optimization", `onap.policies.Optimization.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400120 "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>`_
121 "Optimization.Resource.AffinityPolicy", `onap.policies.optimization.resource.AffinityPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.AffinityPolicy.yaml>`_
122 "Optimization.Resource.DistancePolicy", `onap.policies.optimization.resource.DistancePolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.DistancePolicy.yaml>`_
123 "Optimization.Resource.HpaPolicy", `onap.policies.optimization.resource.HpaPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.HpaPolicy.yaml>`_
124 "Optimization.Resource.OptimizationPolicy", `onap.policies.optimization.resource.OptimizationPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.OptimizationPolicy.yaml>`_
125 "Optimization.Resource.PciPolicy", `onap.policies.optimization.resource.PciPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.PciPolicy.yaml>`_
126 "Optimization.Resource.Vim_fit", `onap.policies.optimization.resource.Vim_fit.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.Vim_fit.yaml>`_
127 "Optimization.Resource.VnfPolicy", `onap.policies.optimization.resource.VnfPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.VnfPolicy.yaml>`_
128 "Optimization.Service", `onap.policies.optimization.Service.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_
129 "Optimization.Service.QueryPolicy", `onap.policies.optimization.service.QueryPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.service.QueryPolicy.yaml>`_
130 "Optimization.Service.SubscriberPolicy", `onap.policies.optimization.service.SubscriberPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.service.SubscriberPolicy.yaml>`_
131 "Controlloop.Guard.Common", `onap.policies.controlloop.guard.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.Common.yaml>`_
132 "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>`_
133 "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>`_
134 "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>`_
Pamela Dragoshcc6265e2020-08-21 10:53:44 -0400135 "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>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400136 "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>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400137 "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>`_
138 "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>`_
139 "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>`_
140 "Naming", `onap.policies.Naming.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Naming.yaml>`_
141 "Native.Drools", `onap.policies.native.Drools.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`_
142 "Native.Xacml", `onap.policies.native.Xacml.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
143 "Native.Apex", `onap.policies.native.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400144
Chenfei Gao7984ada2020-03-17 22:34:15 -0400145We also preload a policy in the policy database. Below is a table listing the preloaded polic(ies).
146
147.. csv-table::
148 :header: "Policy Type Name", "Payload"
149 :widths: 15,10
150
151 "SDNC.Naming", `sdnc.policy.naming.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/sdnc.policy.naming.input.tosca.yaml>`_
152
153Below is a table containing sample well-formed TOSCA compliant policies.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400154
155.. csv-table::
Chenfei Gao0a85b8b2019-09-10 22:22:17 -0400156 :header: "Policy Name", "Payload"
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400157 :widths: 15,10
158
Chenfei Gaodfbc0ad2019-10-01 14:19:39 -0400159 "vCPE.Monitoring.Tosca", `vCPE.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.monitoring.input.tosca.yaml>`_ `vCPE.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.monitoring.input.tosca.json>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400160 "vCPE.Optimization.Tosca", `vCPE.policies.optimization.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policies.optimization.input.tosca.yaml>`_ `vCPE.policies.optimization.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policies.optimization.input.tosca.json>`_
161 "vCPE.Operational.Tosca", `vCPE.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.operational.input.tosca.yaml>`_ `vCPE.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.operational.input.tosca.json>`_
162 "vDNS.Guard.FrequencyLimiting.Tosca", `vDNS.policy.guard.frequencylimiter.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.frequencylimiter.input.tosca.yaml>`_
163 "vDNS.Guard.MinMax.Tosca", `vDNS.policy.guard.minmaxvnfs.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.minmaxvnfs.input.tosca.yaml>`_
164 "vDNS.Guard.Blacklist.Tosca", `vDNS.policy.guard.blacklist.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.blacklist.input.tosca.yaml>`_
Chenfei Gaodfbc0ad2019-10-01 14:19:39 -0400165 "vDNS.Monitoring.Tosca", `vDNS.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.monitoring.input.tosca.yaml>`_ `vDNS.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.monitoring.input.tosca.json>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400166 "vDNS.Operational.Tosca", `vDNS.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.operational.input.tosca.yaml>`_ `vDNS.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.operational.input.tosca.json>`_
Chenfei Gaodfbc0ad2019-10-01 14:19:39 -0400167 "vFirewall.Monitoring.Tosca", `vFirewall.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.monitoring.input.tosca.yaml>`_ `vFirewall.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.monitoring.input.tosca.json>`_
Chenfei Gao7984ada2020-03-17 22:34:15 -0400168 "vFirewall.Operational.Tosca", `vFirewall.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.operational.input.tosca.yaml>`_ `vFirewall.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.operational.input.tosca.json>`_
169 "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>`_
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400170
171
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500172Below is a global API table from where swagger JSON for different types of policy design API can be downloaded.
a.sreekumar332b03d2020-03-27 10:26:05 +0000173
Chenfei Gao55e1f552019-05-21 13:32:30 -0400174Global API Table
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -0400175----------------
Chenfei Gao55e1f552019-05-21 13:32:30 -0400176.. csv-table::
177 :header: "API name", "Swagger JSON"
178 :widths: 10,5
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400179
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400180 "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`"
181 "Statistics API", ":download:`link <swagger/statistics-api.json>`"
182 "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`"
183 "Tosca Policy API", ":download:`link <swagger/policy-api.json>`"
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400184
Chenfei Gao55e1f552019-05-21 13:32:30 -0400185API Swagger
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -0400186-----------
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400187
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500188It is worth noting that we use basic authorization for API access with username and password set to *healthcheck* and *zb!XztG34* respectively.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400189Also, the new APIs support both *http* and *https*.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400190
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500191For every API call, client is encouraged to insert an uuid-type requestID as parameter.
192It is helpful for tracking each http transaction and facilitates debugging.
193Mostly importantly, it complies with Logging requirements v1.2.
liamfallone83e6072020-05-06 13:09:09 +0100194If a client does not provide the requestID in API call, one will be randomly generated
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500195and attached to response header *x-onap-requestid*.
Chenfei Gao55e1f552019-05-21 13:32:30 -0400196
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400197In accordance with `ONAP API Common Versioning Strategy Guidelines <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_,
198in the response of each API call, several custom headers are added::
Chenfei Gao55e1f552019-05-21 13:32:30 -0400199
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500200 x-latestversion: 1.0.0
201 x-minorversion: 0
202 x-patchversion: 0
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400203 x-onap-requestid: e1763e61-9eef-4911-b952-1be1edd9812b
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500204 x-latestversion is used only to communicate an API's latest version.
Chenfei Gao55e1f552019-05-21 13:32:30 -0400205
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400206x-minorversion is used to request or communicate a MINOR version back from the client to the server, and from the server back to the client.
Chenfei Gao55e1f552019-05-21 13:32:30 -0400207
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400208x-patchversion is used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request.
209
210x-onap-requestid is used to track REST transactions for logging purpose, as described above.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400211
212.. swaggerv2doc:: swagger/healthcheck-api.json
213
214.. swaggerv2doc:: swagger/statistics-api.json
215
216.. swaggerv2doc:: swagger/policytype-api.json
217
218.. swaggerv2doc:: swagger/policy-api.json
219
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500220When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
221but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA
222policy should strictly match the policy type name it derives.
223Please check out the sample policies in above policy table.
224
225Also, in the POST payload passed into each policy or policy type creation call (i.e. POST API invocation), the client needs to explicitly
226specify the version of the policy or policy type to create. That being said, the "version" field is mandatory in the TOSCA service template
Chenfei Gao7984ada2020-03-17 22:34:15 -0400227formatted policy or policy type payload. If the version is missing, that POST call will return "406 - Not Acceptable" and
228the policy or policy type to create will not be stored in the database.
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500229
230To avoid inconsistent versions between the database and policies deployed in the PDPs, policy API REST service employs some enforcement
231rules that validate the version specified in the POST payload when a new version is to create or an existing version to update.
232Policy API will not blindly override the version of the policy or policy type to create/update.
233Instead, we encourage the client to carefully select a version for the policy or policy type to change and meanwhile policy API will check the validity
234of the version and feed an informative warning back to the client if the specified version is not good.
235To be specific, the following rules are implemented to enforce the version:
236
Chenfei Gao7984ada2020-03-17 22:34:15 -04002371. If the incoming version is not in the database, we simply insert it. For example: if policy version 1.0.0 is stored in the database and now
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500238 a client wants to create the same policy with updated version 3.0.0, this POST call will succeed and return "200" to the client.
239
Chenfei Gao7984ada2020-03-17 22:34:15 -04002402. If the incoming version is already in the database and the incoming payload is different from the same version in the database,
241 "406 - Not Acceptable" will be returned. This forces the client to update the version of the policy if the policy is changed.
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500242
Chenfei Gao7984ada2020-03-17 22:34:15 -04002433. If a client creates a version of a policy and wishes to update a property on the policy, they must delete that version of the policy and re-create it.
244
2454. If multiple policies are included in the POST payload, policy API will also check if duplicate version exists in between
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500246 any two policies or policy types provided in the payload. For example, a client provides a POST payload which includes two policies with the same
247 name and version but different policy properties. This POST call will fail and return "406" error back to the calling application along with a
248 message such as "duplicate policy {name}:{version} found in the payload".
249
Chenfei Gao7984ada2020-03-17 22:34:15 -04002505. The same version validation is applied to policy types too.
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500251
Chenfei Gao7984ada2020-03-17 22:34:15 -04002526. To avoid unnecessary id/version inconsistency between the ones specified in the entity fields and the ones returned in the metadata field,
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500253 "policy-id" and "policy-version" in the metadata will only be set by policy API. Any incoming explicit specification in the POST payload will be
254 ignored. For example, A POST payload has a policy with name "sample-policy-name1" and version "1.0.0" specified. In this policy, the metadata
255 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
256 metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0".
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400257
Chenfei Gao7984ada2020-03-17 22:34:15 -0400258Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500259or policy type at a time for safety purpose. If client has the need to delete multiple or a group of policies or policy types,
Chenfei Gao7984ada2020-03-17 22:34:15 -0400260they will need to delete them one by one.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400261
262Sample API Curl Commands
263-------------------------
264
liamfallone83e6072020-05-06 13:09:09 +0100265From an API client perspective, using *http* or *https* does not make much difference to the curl command.
Chenfei Gao6d69ff92020-01-13 13:20:34 -0500266Here we list some sample curl commands (using *http*) for POST, GET and DELETE monitoring and operational policies that are used in vFirewall use case.
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400267JSON payload for POST calls can be downloaded from policy table above.
268
Pamela Dragoshf65c8ff2020-04-29 08:23:12 -0400269If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**.
270
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400271Create vFirewall Monitoring Policy::
Pamela Dragosh56316602020-08-20 09:16:20 -0400272 curl --user 'healthcheck: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
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400273
274Get vFirewall Monitoring Policy::
Pamela Dragosh56316602020-08-20 09:16:20 -0400275 curl --user 'healthcheck: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"
Chenfei Gao7984ada2020-03-17 22:34:15 -0400276
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400277Delete vFirewall Monitoring Policy::
Pamela Dragosh56316602020-08-20 09:16:20 -0400278 curl --user 'healthcheck: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"
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400279
280Create vFirewall Operational Policy::
Chenfei Gao7984ada2020-03-17 22:34:15 -0400281 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
282
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400283Get vFirewall Operational Policy::
Chenfei Gao7984ada2020-03-17 22:34:15 -0400284 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"
285
Chenfei Gaoaf35b6a2019-05-21 17:40:21 -0400286Delete vFirewall Operational Policy::
Chenfei Gao7984ada2020-03-17 22:34:15 -0400287 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"
puthuparambil.adityaa6c09a22020-07-27 12:09:40 +0100288
289Get all available policies::
290 curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json"
291
292Get version 1.0.0 of vFirewall Monitoring Policy::
293 curl --user 'healthcheck: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"
294
295Delete version 1.0.0 of vFirewall Monitoring Policy::
296 curl --user 'healthcheck: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"