X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapi%2Fapi.rst;h=aa31c06492ac76d22922b791e6946300cede6b44;hb=078d92c0c0f4d4be3aa8e0b6808380159bd7d9f2;hp=222a2bcee231f878ba3f92e892cc287f5f264767;hpb=2242f9b55f475a086dc414cd48f8abd92dc897cf;p=policy%2Fparent.git diff --git a/docs/api/api.rst b/docs/api/api.rst index 222a2bce..aa31c064 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -2,6 +2,7 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. THIS IS USED INTERNALLY IN POLICY ONLY .. _api-label: Policy Life Cycle API @@ -10,27 +11,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 -` 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. +` 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 `_ -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 `_. + +:: + + 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 +76,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 +99,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 @@ -91,7 +133,6 @@ To ease policy creation, we preload several widely used policy types in policy d "Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml `_ "Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml `_ "Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml `_ - "Controlloop.Operational", `onap.policies.controlloop.Operational.yaml `_ "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml `_ "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml `_ "Controlloop.Operational.Common.Drools", `onap.policies.controlloop.operational.common.Drools.yaml `_ @@ -139,7 +180,6 @@ Global API Table "Statistics API", ":download:`link `" "Tosca Policy Type API", ":download:`link `" "Tosca Policy API", ":download:`link `" - "Legacy Operational Policy API", ":download:`link `" API Swagger ----------- @@ -150,7 +190,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 `_, @@ -214,8 +254,6 @@ To be specific, the following rules are implemented to enforce the version: 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 metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0". -.. swaggerv2doc:: swagger/operational-policy-api.json - Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy 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. @@ -223,7 +261,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. @@ -246,3 +284,12 @@ Get vFirewall Operational Policy:: Delete vFirewall Operational Policy:: 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" + +Get all available policies:: + curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json" + +Get version 1.0.0 of vFirewall Monitoring Policy:: + 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" + +Delete version 1.0.0 of vFirewall Monitoring Policy:: + 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"