Add documentation for PAP
[policy/parent.git] / docs / pap / pap.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3
4 .. _pap-label:
5
6 Policy Administration Point (PAP) Architecture
7 ==============================================
8 .. toctree::
9
10 The PAP keeps track of PDPs, supporting the deployment of PDP groups and the
11 deployment of a *policy set* across those PDP groups.  Policies are created
12 using the Policy API, but are deployed via the PAP. 
13
14 A PAP is stateless in
15 a RESTful sense, using the database (persistent storage) to track PDPs and
16 the deployment of policies to those PDPs. In short, policy management on PDPs
17 is the responsibility of PAPs; management of policy sets or policies by any
18 other manner is not permitted.
19
20 Because the PDP is the main unit of scalability in the Policy Framework, the
21 framework is designed to allow PDPs in a PDP group to arbitrarily appear and
22 disappear and for policy consistency across all PDPs in a PDP group to be
23 easily maintained.  The PAP is responsible for controlling the state across
24 the PDPs in a PDP group. The PAP interacts with the Policy database and
25 transfers policy sets to PDPs.
26
27
28 REST API
29 --------
30
31 PAP supports the operations listed in the following table, via its REST API:
32
33 .. csv-table::
34    :header: "Operation", "Description"
35    :widths: 25,70
36
37    "Health check", "Queries the health of the PAP"
38    "Statistics", "Queries various statistics"
39    "PDP state change", "Changes the state of all PDPs in a PDP Group"
40    "PDP Group create/update", "Creates/updates PDP Groups"
41    "PDP Group delete", "Deletes a PDP Group"
42    "PDP Group query", "Queries all PDP Groups"
43    "Deploy policy", "Deploys one or more policies to the PDPs"
44    "Undeploy policy", "Undeploys a policy from the PDPs"
45
46
47 DMaaP API
48 ---------
49
50 PAP interacts with the PDPs via the DMaaP Message Router.  The messages listed
51 in the following table are transmitted via DMaaP:
52
53 .. csv-table::
54    :header: "Message", "Direction", "Description"
55    :widths: 25,10,70
56
57    "PDP status", "Incoming", "Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP"
58    "PDP update", "Outgoing", "Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP"
59    "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup"
60
61
62 PAP REST API Swagger
63 --------------------
64
65 It is worth noting that we use basic authorization for access with user name
66 and password set to *healthcheck* and *zb!XztG34*, respectively.
67
68 For every call, the client is encouraged to insert a uuid-type *requestID* as
69 parameter. It is helpful for tracking each http transaction and facilitates
70 debugging. More importantly, it complies with Logging requirements v1.2. If
71 the client does not provide the requestID in a call, one will be randomly
72 generated and attached to the response header, *x-onap-requestid*.
73
74 In accordance with `ONAP API Common Versioning Strategy Guidelines <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_,
75 several custom headers are added in the response to each call:
76
77 .. csv-table::
78    :header: "Header", "Example value", "Description"
79    :widths: 25,10,70
80
81    "x-latestversion", "1.0.0", "latest version of the API"
82    "x-minorversion", "0", "MINOR version of the API"
83    "x-patchversion", "0", "PATCH version of the API"
84    "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
85     
86
87 .. swaggerv2doc:: swagger/health-check-pap.json
88
89 .. swaggerv2doc:: swagger/statistics-pap.json
90
91 Note: while this API is supported, most of the statistics
92 are not currently updated; that work has been deferred to a later release.
93
94 .. swaggerv2doc:: swagger/state-change-pap.json
95
96 .. swaggerv2doc:: swagger/group-pap.json
97
98 Note: due to current limitations, if a subgroup is to be deleted from a PDP
99 Group, then the policies must be removed from the subgroup in one request,
100 and then the subgroup deleted in a subsequent request.
101
102 .. swaggerv2doc:: swagger/group-delete-pap.json
103
104 .. swaggerv2doc:: swagger/group-query-pap.json
105
106 .. swaggerv2doc:: swagger/policy-deploy-pap.json
107
108 Note: the policy version is optional.  If left unspecified, then the latest
109 version of the policy is deployed. On the other hand, if it is specified, it
110 may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
111
112 .. swaggerv2doc:: swagger/policy-undeploy-pap.json
113
114 Note: if the policy version is specified, then it
115 may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
116 On the other hand, if left unspecified, then the latest deployed version
117 will be undeployed.
118
119 Note: due to current limitations, a fully qualified policy version must
120 always be specified.
121
122 End of Document