Update API documentation

API documentation updated to clarify and explain how TOSCA checks are
carried out, warnings added to the docuemtation to explain how the
policy type and data type hierarchy and policy to policy type references
are checked and under what circumstances errors are reported.

Issue-ID: POLICY-2500
Change-Id: I3cbb7d45ed9997b04b523a4b3cfe32950df71262
Signed-off-by: liamfallon <liam.fallon@est.tech>

1 files changed, 63 insertions, 22 deletions

diff --git a/docs/api/api.rst b/docs/api/api.rst
index 222a2bce..3ba8c43e 100644
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -10,27 +10,64 @@ Policy Life Cycle API
 .. contents::
     :depth: 2
 
-The purpose of this API is to support CRUD of TOSCA *PolicyType* entities. This API is provided by the
+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. Policy design API backend is running in an independent building block component of policy framework
-that provides REST service for aforementioned CRUD behaviors. Policy design API component interacts with a policy database
-for storing and fetching new policies or policy types as needed. Apart from CRUD, API is also exposed for clients to retrieve
-healthcheck status of this API REST service and statistics report including a variety of counters that reflect the history
-of API invocation.
+<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 type and policy. A policy type is equivalent to the policy model mentioned by clients before Dublin release.
-Both policy type and policy are included in a TOSCA Service Template which is used as the entity passed into API POST call
-and the entity returned by API GET and DELETE calls. More details are presented in following sessions.
-We encourage clients to compose all kinds of policies and corresponding policy types in well-formed TOSCA Service Template.
-One Service Template can contain one or more policies and policy types. Each policy type can have multiple policies created
-atop. In other words, different policies can match the same or different policy types. Existence of a policy type is a prerequisite
-of creating such type of policies. In the payload body of each policy to create, policy type name and version should be indicated and
-the specified policy type should be valid and existing in policy database.
+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 <hhttps://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. The TOSCA
-fields below are valid on API calls:
+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**
@@ -38,12 +75,16 @@ fields below are valid on API calls:
 (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
+                                         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
+                                         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
+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
 ============ ======= ======== ========== ===============================================================================
@@ -57,7 +98,7 @@ triggers     R       O        N/A        Specification of policy triggers, not c
   implementations is disabled.
 
 .. note::
-  Policy types that are in use (referenced by defined Policies) may not be deleted.
+  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
@@ -150,7 +191,7 @@ Also, the new APIs support both *http* and *https*.
 For every API call, client is encouraged to insert an uuid-type requestID as parameter.
 It is helpful for tracking each http transaction and facilitates debugging.
 Mostly importantly, it complies with Logging requirements v1.2.
-If client does not provider the requestID in API call, one will be randomly generated
+If a client does not provide the requestID in API call, one will be randomly generated
 and attached to response header *x-onap-requestid*.
 
 In accordance with `ONAP API Common Versioning Strategy Guidelines <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_,
@@ -223,7 +264,7 @@ they will need to delete them one by one.
 Sample API Curl Commands
 -------------------------
 
-From API client perspective, using *http* or *https* does not have much difference in curl command.
+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.
 JSON payload for POST calls can be downloaded from policy table above.