From 5eeeeddd1833e67ad9c285032abc3fb3bbde0b2d Mon Sep 17 00:00:00 2001 From: Jim Hahn Date: Wed, 11 Dec 2019 16:25:56 -0500 Subject: Document new PAP REST APIs Includes the Pdp Group create/update API and the Deployment API. Issue-ID: POLICY-2281 Signed-off-by: Jim Hahn Change-Id: Ifde0491b029eb377c4f3083c784663df968b9d1b --- docs/pap/pap.rst | 31 +++- docs/pap/request/deployment-batch-pap-req.json | 19 +++ docs/pap/request/group-pap-req.json | 39 ----- docs/pap/request/groups-batch-pap-req.json | 34 ++++ docs/pap/swagger/deployments-batch-pap.json | 150 ++++++++++++++++ docs/pap/swagger/group-pap.json | 226 ------------------------- docs/pap/swagger/groups-batch-pap.json | 215 +++++++++++++++++++++++ 7 files changed, 445 insertions(+), 269 deletions(-) create mode 100644 docs/pap/request/deployment-batch-pap-req.json delete mode 100644 docs/pap/request/group-pap-req.json create mode 100644 docs/pap/request/groups-batch-pap-req.json create mode 100644 docs/pap/swagger/deployments-batch-pap.json delete mode 100644 docs/pap/swagger/group-pap.json create mode 100644 docs/pap/swagger/groups-batch-pap.json diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst index d061c815..a9f6772b 100644 --- a/docs/pap/pap.rst +++ b/docs/pap/pap.rst @@ -142,18 +142,22 @@ Here is a sample response: The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full description of PDP group states, see the :ref:`ONAP Policy Framework Architecture ` page. -.. swaggerv2doc:: swagger/group-pap.json +.. swaggerv2doc:: swagger/groups-batch-pap.json This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated in a single POST operation by specifying more than one PDP group in the POST operation body. +This can be used to update the policy types supported by various subgroups. +However, it cannot be used to update policies; that is done using one of +the deployment requests. Consequently, the "policy" property of this +request will be ignored. .. note:: Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from - the subgroup in one request, and then the subgroup deleted in a subsequent request. + the subgroup first. Here is a sample request: -.. literalinclude:: request/group-pap-req.json +.. literalinclude:: request/groups-batch-pap-req.json :language: json .. swaggerv2doc:: swagger/group-delete-pap.json @@ -170,13 +174,32 @@ Here is a sample response: .. literalinclude:: response/group-query-pap-resp.json :language: json +.. swaggerv2doc:: swagger/deployments-batch-pap.json + +This operation allows policies to be deployed on specific PDP groups. +Each subgroup includes an "action" property, which is used to indicate +that the policies are being added (POST) to the subgroup, deleted (DELETE) +from the subgroup, or that the subgroup's entire set of policies is being +replaced (PATCH) by a new set of policies. As such, a subgroup may appear +more than once in a single request, one time to delete some policies and +another time to add new policies to the same subgroup. + +Here is a sample request: + +.. literalinclude:: request/deployment-batch-pap-req.json + :language: json + .. swaggerv2doc:: swagger/policy-deploy-pap.json -This operation allows policies to be deployed on PDP groups. +This operation allows policies to be deployed across all relevant PDP groups. +PAP will deploy the specified policies to all relevant subgroups. Only the +policies supported by a given subgroup will be deployed to that subgroup. .. note:: The policy version is optional. If left unspecified, then the latest version of the policy is deployed. On the other hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2"). + In addition, a subgroup to which a policy is being deployed must have at + least one PDP instance, otherwise the request will be rejected. Here is a sample request: diff --git a/docs/pap/request/deployment-batch-pap-req.json b/docs/pap/request/deployment-batch-pap-req.json new file mode 100644 index 00000000..6577bed7 --- /dev/null +++ b/docs/pap/request/deployment-batch-pap-req.json @@ -0,0 +1,19 @@ +{ + "groups": [ + { + "name": "SampleGroup", + "deploymentSubgroups": [ + { + "pdpType": "apex", + "action": "POST", + "policies": [ + { + "name": "onap.controllloop.operational.apex.bbs.EastRegion", + "version": "1.0.0" + } + ] + } + ] + } + ] +} diff --git a/docs/pap/request/group-pap-req.json b/docs/pap/request/group-pap-req.json deleted file mode 100644 index ebe38b92..00000000 --- a/docs/pap/request/group-pap-req.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "groups": [ - { - "name": "SampleGroup", - "pdpGroupState": "PASSIVE", - "pdpSubgroups": [ - { - "pdpType": "apex", - "desiredInstanceCount": 2, - "properties": {}, - "supportedPolicyTypes": [ - { - "name": "onap.controllloop.operational.apex.bbs", - "version": "1.0.0" - } - ], - "policies": [ - { - "name": "onap.controllloop.operational.apex.bbs.EastRegion", - "version": "1.0.0" - } - ] - }, - { - "pdpType": "xacml", - "desiredInstanceCount": 1, - "properties": {}, - "supportedPolicyTypes": [ - { - "name": "onap.policies.monitoring.cdap.tca.hi.lo.app", - "version": "1.0.0" - } - ], - "policies": [] - } - ] - } - ] -} diff --git a/docs/pap/request/groups-batch-pap-req.json b/docs/pap/request/groups-batch-pap-req.json new file mode 100644 index 00000000..2f909413 --- /dev/null +++ b/docs/pap/request/groups-batch-pap-req.json @@ -0,0 +1,34 @@ +{ + "groups": [ + { + "name": "SampleGroup", + "pdpGroupState": "PASSIVE", + "pdpSubgroups": [ + { + "pdpType": "apex", + "desiredInstanceCount": 2, + "properties": {}, + "supportedPolicyTypes": [ + { + "name": "onap.controllloop.operational.apex.bbs", + "version": "1.0.0" + } + ], + "policies": [] + }, + { + "pdpType": "xacml", + "desiredInstanceCount": 1, + "properties": {}, + "supportedPolicyTypes": [ + { + "name": "onap.policies.monitoring.cdap.tca.hi.lo.app", + "version": "1.0.0" + } + ], + "policies": [] + } + ] + } + ] +} diff --git a/docs/pap/swagger/deployments-batch-pap.json b/docs/pap/swagger/deployments-batch-pap.json new file mode 100644 index 00000000..58289fb9 --- /dev/null +++ b/docs/pap/swagger/deployments-batch-pap.json @@ -0,0 +1,150 @@ +{ + "swagger" : "2.0", + "basePath" : "/", + "tags" : [ { + "name" : "DeploymentsUpdate" + } ], + "schemes" : [ "http", "https" ], + "consumes" : [ "application/json", "application/yaml" ], + "produces" : [ "application/json", "application/yaml" ], + "paths" : { + "/policy/pap/v1/pdps/deployments/batch" : { + "post" : { + "tags" : [ "DeploymentsUpdate" ], + "summary" : "Updates policy deployments within specific PDP groups", + "description" : "Updates policy deployments within specific PDP groups, returning optional error details", + "operationId" : "updateGroupPolicies", + "produces" : [ "application/json", "application/yaml" ], + "parameters" : [ { + "name" : "X-ONAP-RequestID", + "in" : "header", + "description" : "RequestID for http transaction", + "required" : false, + "type" : "string", + "format" : "uuid" + }, { + "in" : "body", + "name" : "body", + "description" : "List of PDP Group Deployments", + "required" : true, + "schema" : { + "$ref" : "#/definitions/DeploymentGroups" + } + } ], + "responses" : { + "200" : { + "description" : "successful operation", + "headers" : { + "X-MinorVersion" : { + "type" : "string", + "description" : "Used to request or communicate a MINOR version back from the client to the server, and from the server back to the client" + }, + "X-PatchVersion" : { + "type" : "string", + "description" : "Used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request" + }, + "X-LatestVersion" : { + "type" : "string", + "description" : "Used only to communicate an API's latest version" + }, + "X-ONAP-RequestID" : { + "type" : "string", + "format" : "uuid", + "description" : "Used to track REST transactions for logging purpose" + } + }, + "schema" : { + "$ref" : "#/definitions/PdpGroupDeployResponse" + } + }, + "401" : { + "description" : "Authentication Error" + }, + "403" : { + "description" : "Authorization Error" + }, + "500" : { + "description" : "Internal Server Error" + } + }, + "security" : [ { + "basicAuth" : [ ] + } ], + "x-interface info" : { + "api-version" : "1.0.0", + "last-mod-release" : "Dublin" + } + } + } + }, + "securityDefinitions" : { + "basicAuth" : { + "description" : "", + "type" : "basic" + } + }, + "definitions" : { + "ToscaPolicyIdentifier" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" + }, + "version" : { + "type" : "string" + } + } + }, + "PdpGroupDeployResponse" : { + "type" : "object", + "properties" : { + "errorDetails" : { + "type" : "string" + } + } + }, + "DeploymentGroup" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" + }, + "deploymentSubgroups" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/DeploymentSubGroup" + } + } + } + }, + "DeploymentGroups" : { + "type" : "object", + "properties" : { + "groups" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/DeploymentGroup" + } + } + } + }, + "DeploymentSubGroup" : { + "type" : "object", + "properties" : { + "pdpType" : { + "type" : "string" + }, + "action" : { + "type" : "string", + "enum" : [ "POST", "DELETE", "PATCH" ] + }, + "policies" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/ToscaPolicyIdentifier" + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/pap/swagger/group-pap.json b/docs/pap/swagger/group-pap.json deleted file mode 100644 index 1298fffa..00000000 --- a/docs/pap/swagger/group-pap.json +++ /dev/null @@ -1,226 +0,0 @@ -{ - "swagger" : "2.0", - "basePath" : "/", - "tags" : [ { - "name" : "PdpGroupDeploy" - } ], - "schemes" : [ "http", "https" ], - "consumes" : [ "application/json" ], - "produces" : [ "application/json" ], - "paths" : { - "/policy/pap/v1/pdps" : { - "post" : { - "tags" : [ "PdpGroupDeploy" ], - "summary" : "Deploy or update PDP Groups", - "description" : "Deploys or updates a PDP Group, returning optional error details", - "operationId" : "deployGroup", - "produces" : [ "application/json" ], - "parameters" : [ { - "name" : "X-ONAP-RequestID", - "in" : "header", - "description" : "RequestID for http transaction", - "required" : false, - "type" : "string", - "format" : "uuid" - }, { - "in" : "body", - "name" : "body", - "description" : "List of PDP Group Configuration", - "required" : true, - "schema" : { - "$ref" : "#/definitions/PdpGroups" - } - } ], - "responses" : { - "200" : { - "description" : "successful operation", - "headers" : { - "X-MinorVersion" : { - "type" : "string", - "description" : "Used to request or communicate a MINOR version back from the client to the server, and from the server back to the client" - }, - "X-PatchVersion" : { - "type" : "string", - "description" : "Used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request" - }, - "X-LatestVersion" : { - "type" : "string", - "description" : "Used only to communicate an API's latest version" - }, - "X-ONAP-RequestID" : { - "type" : "string", - "format" : "uuid", - "description" : "Used to track REST transactions for logging purpose" - } - }, - "schema" : { - "$ref" : "#/definitions/PdpGroupDeployResponse" - } - }, - "401" : { - "description" : "Authentication Error" - }, - "403" : { - "description" : "Authorization Error" - }, - "500" : { - "description" : "Internal Server Error" - } - }, - "security" : [ { - "basicAuth" : [ ] - } ], - "x-interface info" : { - "api-version" : "1.0.0", - "last-mod-release" : "Dublin" - } - } - } - }, - "securityDefinitions" : { - "basicAuth" : { - "description" : "", - "type" : "basic" - } - }, - "definitions" : { - "Pdp" : { - "type" : "object", - "properties" : { - "instanceId" : { - "type" : "string" - }, - "pdpState" : { - "type" : "string", - "enum" : [ "PASSIVE", "SAFE", "TEST", "ACTIVE", "TERMINATED" ] - }, - "healthy" : { - "type" : "string", - "enum" : [ "HEALTHY", "NOT_HEALTHY", "TEST_IN_PROGRESS", "UNKNOWN" ] - }, - "message" : { - "type" : "string" - } - } - }, - "PdpGroup" : { - "type" : "object", - "properties" : { - "name" : { - "type" : "string" - }, - "description" : { - "type" : "string" - }, - "pdpGroupState" : { - "type" : "string", - "enum" : [ "PASSIVE", "SAFE", "TEST", "ACTIVE", "TERMINATED" ] - }, - "properties" : { - "type" : "object", - "additionalProperties" : { - "type" : "string" - } - }, - "pdpSubgroups" : { - "type" : "array", - "items" : { - "$ref" : "#/definitions/PdpSubGroup" - } - } - } - }, - "PdpGroups" : { - "type" : "object", - "properties" : { - "groups" : { - "type" : "array", - "items" : { - "$ref" : "#/definitions/PdpGroup" - } - } - } - }, - "PdpSubGroup" : { - "type" : "object", - "properties" : { - "pdpType" : { - "type" : "string" - }, - "supportedPolicyTypes" : { - "type" : "array", - "items" : { - "$ref" : "#/definitions/ToscaPolicyTypeIdentifier" - } - }, - "policies" : { - "type" : "array", - "items" : { - "$ref" : "#/definitions/ToscaPolicyIdentifier" - } - }, - "currentInstanceCount" : { - "type" : "integer", - "format" : "int32" - }, - "desiredInstanceCount" : { - "type" : "integer", - "format" : "int32" - }, - "properties" : { - "type" : "object", - "additionalProperties" : { - "type" : "string" - } - }, - "pdpInstances" : { - "type" : "array", - "items" : { - "$ref" : "#/definitions/Pdp" - } - } - } - }, - "ToscaPolicyIdentifier" : { - "type" : "object", - "properties" : { - "name" : { - "type" : "string" - }, - "version" : { - "type" : "string" - } - } - }, - "ToscaPolicyTypeIdentifier" : { - "type" : "object", - "properties" : { - "name" : { - "type" : "string" - }, - "version" : { - "type" : "string" - } - } - }, - "PdpGroupDeployResponse" : { - "type" : "object", - "properties" : { - "errorDetails" : { - "type" : "string" - } - } - }, - "ToscaPolicyIdentifierOptVersion" : { - "type" : "object", - "properties" : { - "name" : { - "type" : "string" - }, - "version" : { - "type" : "string" - } - } - } - } -} diff --git a/docs/pap/swagger/groups-batch-pap.json b/docs/pap/swagger/groups-batch-pap.json new file mode 100644 index 00000000..8a1899e3 --- /dev/null +++ b/docs/pap/swagger/groups-batch-pap.json @@ -0,0 +1,215 @@ +{ + "swagger" : "2.0", + "basePath" : "/", + "tags" : [ { + "name" : "PdpGroupUpdate" + } ], + "schemes" : [ "http", "https" ], + "consumes" : [ "application/json", "application/yaml" ], + "produces" : [ "application/json", "application/yaml" ], + "paths" : { + "/policy/pap/v1/pdps/groups/batch" : { + "post" : { + "tags" : [ "PdpGroupUpdate" ], + "summary" : "Create or update PDP Groups", + "description" : "Create or update one or more PDP Groups, returning optional error details", + "operationId" : "createOrUpdateGroups", + "produces" : [ "application/json", "application/yaml" ], + "parameters" : [ { + "name" : "X-ONAP-RequestID", + "in" : "header", + "description" : "RequestID for http transaction", + "required" : false, + "type" : "string", + "format" : "uuid" + }, { + "in" : "body", + "name" : "body", + "description" : "List of PDP Group Configuration", + "required" : true, + "schema" : { + "$ref" : "#/definitions/PdpGroups" + } + } ], + "responses" : { + "200" : { + "description" : "successful operation", + "headers" : { + "X-MinorVersion" : { + "type" : "string", + "description" : "Used to request or communicate a MINOR version back from the client to the server, and from the server back to the client" + }, + "X-PatchVersion" : { + "type" : "string", + "description" : "Used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request" + }, + "X-LatestVersion" : { + "type" : "string", + "description" : "Used only to communicate an API's latest version" + }, + "X-ONAP-RequestID" : { + "type" : "string", + "format" : "uuid", + "description" : "Used to track REST transactions for logging purpose" + } + }, + "schema" : { + "$ref" : "#/definitions/PdpGroupUpdateResponse" + } + }, + "401" : { + "description" : "Authentication Error" + }, + "403" : { + "description" : "Authorization Error" + }, + "500" : { + "description" : "Internal Server Error" + } + }, + "security" : [ { + "basicAuth" : [ ] + } ], + "x-interface info" : { + "api-version" : "1.0.0", + "last-mod-release" : "Dublin" + } + } + } + }, + "securityDefinitions" : { + "basicAuth" : { + "description" : "", + "type" : "basic" + } + }, + "definitions" : { + "PdpGroupUpdateResponse" : { + "type" : "object", + "properties" : { + "errorDetails" : { + "type" : "string" + } + } + }, + "Pdp" : { + "type" : "object", + "properties" : { + "instanceId" : { + "type" : "string" + }, + "pdpState" : { + "type" : "string", + "enum" : [ "PASSIVE", "SAFE", "TEST", "ACTIVE", "TERMINATED" ] + }, + "healthy" : { + "type" : "string", + "enum" : [ "HEALTHY", "NOT_HEALTHY", "TEST_IN_PROGRESS", "UNKNOWN" ] + }, + "message" : { + "type" : "string" + } + } + }, + "PdpGroup" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" + }, + "description" : { + "type" : "string" + }, + "pdpGroupState" : { + "type" : "string", + "enum" : [ "PASSIVE", "SAFE", "TEST", "ACTIVE", "TERMINATED" ] + }, + "properties" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } + }, + "pdpSubgroups" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/PdpSubGroup" + } + } + } + }, + "PdpGroups" : { + "type" : "object", + "properties" : { + "groups" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/PdpGroup" + } + } + } + }, + "PdpSubGroup" : { + "type" : "object", + "properties" : { + "pdpType" : { + "type" : "string" + }, + "supportedPolicyTypes" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/ToscaPolicyTypeIdentifier" + } + }, + "policies" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/ToscaPolicyIdentifier" + } + }, + "currentInstanceCount" : { + "type" : "integer", + "format" : "int32" + }, + "desiredInstanceCount" : { + "type" : "integer", + "format" : "int32" + }, + "properties" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } + }, + "pdpInstances" : { + "type" : "array", + "items" : { + "$ref" : "#/definitions/Pdp" + } + } + } + }, + "ToscaPolicyIdentifier" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" + }, + "version" : { + "type" : "string" + } + } + }, + "ToscaPolicyTypeIdentifier" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" + }, + "version" : { + "type" : "string" + } + } + } + } +} \ No newline at end of file -- cgit 1.2.3-korg