+ :depth: 2
+
+The purpose of this API is to support CRUD of TOSCA *PolicyType* and *Policy* entities. This API is provided by the
+*PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
+<architecture-label>` page. The Policy design API backend is running in an independent building block component of the
+policy framework that provides REST services for the aforementioned CRUD behaviors. The Policy design API component interacts
+with a policy database for storing and fetching new policies or policy types as needed. Apart from CRUD, an API is also
+exposed for clients to retrieve healthcheck status of the API REST service and statistics report including a variety of
+counters that reflect the history of API invocation.
+
+We strictly follow `TOSCA Specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`_
+to define policy types and policies. A policy type defines the schema for a policy, expressing the properties, targets, and triggers
+that a policy may have. The type (string, int etc) and constraints (such as the range of legal values) of each property is defined
+in 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
+POST call and the entity returned by API GET and DELETE calls. More details are presented in following sections. Policy Types and Policies
+can be composed for any given domain of application. All Policy Types and Policies must be composed as well-formed TOSCA Service Templates.
+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.
+See also `the examples in Github <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`_.
+
+::
+
+ onap.policies.Optimization.yaml
+ onap.policies.optimization.Resource.yaml
+ onap.policies.optimization.resource.AffinityPolicy.yaml
+ onap.policies.optimization.resource.DistancePolicy.yaml
+ onap.policies.optimization.resource.HpaPolicy.yaml
+ onap.policies.optimization.resource.OptimizationPolicy.yaml
+ onap.policies.optimization.resource.PciPolicy.yaml
+ onap.policies.optimization.resource.Vim_fit.yaml
+ onap.policies.optimization.resource.VnfPolicy.yaml
+ onap.policies.optimization.Service.yaml
+ onap.policies.optimization.service.QueryPolicy.yaml
+ onap.policies.optimization.service.SubscriberPolicy.yaml
+
+Custom 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.
+
+.. warning::
+ When creating a Policy Type, the ancestors of the Policy Type and all its custom Data Type definitions and ancestors MUST either already
+ exist in the database or MUST also be defined in the incoming TOSCA Service Template. Requests with missing or bad references are rejected
+ by the API.
+
+Each 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.
+
+.. warning::
+ The Policy Type specified for a Policy MUST exist in the database before the policy can be created. Requests with missing or bad
+ Policy Type references are rejected by the API.
+
+The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for
+use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework.
+
+.. warning::
+ If a TOSCA entity (Data Type, Policy Type, or Policy with a certain version) already exists in the database and an attempt is made
+ to re-create the entity with different fields, the API will reject the request with the error message "entity in incoming fragment
+ does not equal existing entity". In such cases, delete the Policy or Policy Type and re-create it using the API.
+
+
+The TOSCA fields below are valid on API calls:
+
+============ ======= ======== ========== ===============================================================================
+**Field** **GET** **POST** **DELETE** **Comment**
+============ ======= ======== ========== ===============================================================================
+(name) M M M The definition of the reference to the Policy Type, GET allows ranges to be
+ specified
+version O M C GET allows ranges to be specified, must be specified if more than one version
+ of the Policy Type exists and a specific version is required
+description R O N/A Desciption of the Policy Type
+derived_from R C N/A Must be specified when a Policy Type is derived from another Policy Type such
+ as in the case of derived Monitoring Policy Types. The referenced Policy Type
+ must either already exist in the database or be defined as another policy type
+ in the incoming TOSCA service template
+metadata R O N/A Metadata for the Policy Type
+properties R M N/A This field holds the specification of the specific Policy Type in ONAP. Any user
+ defined data types specified on properties must either already exist in the
+ database or be defined in the incoming TOSCA service template
+targets R O N/A A list of node types and/or group types to which the Policy Type can be applied
+triggers R O N/A Specification of policy triggers, not currently supported in ONAP
+============ ======= ======== ========== ===============================================================================
+
+.. note::
+ On this and subsequent tables, use the following legend: M-Mandatory, O-Optional, R-Read-only, C-Conditional.
+ Conditional means the field is mandatory when some other field is present.
+
+.. note::
+ Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type
+ implementations is disabled.
+
+.. note::
+ Policy types that are in use (referenced by defined Policies and/or child policy types) may not be deleted.
+
+.. note::
+ 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.
+
+.. _policy-preload-label:
+
+.. csv-table::
+ :header: "Policy Type Name", "Payload"
+ :widths: 15,10
+
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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>`_
+ "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.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>`_
+ "Naming", `onap.policies.Naming.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Naming.yaml>`_
+ "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>`_
+ "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>`_
+ "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>`_
+
+We also preload a policy in the policy database. Below is a table listing the preloaded polic(ies).