From 7f961c34cd224b9d38f3549e3660b25a8aafd799 Mon Sep 17 00:00:00 2001 From: Saryu Shah Date: Fri, 26 Oct 2018 00:33:08 +0000 Subject: [PATCH] API Doc: Add examples API Doc: Add examples ------------------------------------------------------------- Change-Id: Ia219b06cdb05ef67c40c8920ea05087a0bf249d8 Issue-ID: POLICY-1219 Signed-off-by: Saryu Shah --- docs/platform/offeredapis.rst | 600 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 600 insertions(+) diff --git a/docs/platform/offeredapis.rst b/docs/platform/offeredapis.rst index 811a12891..4a76fb770 100644 --- a/docs/platform/offeredapis.rst +++ b/docs/platform/offeredapis.rst @@ -33,6 +33,606 @@ POLICY API Details .. swaggerv2doc:: api-docs.json +Examples +^^^^^^^^ + +**SAMPLE JAVA CLIENT CODE** + + .. code-block:: java + :caption: Get Config Example + :linenos: + + package org.onap.policyEngine; + + import java.util.Collection; + + import org.onap.policy.api.ConfigRequestParameters; + import org.onap.policy.api.PolicyConfig; + import org.onap.policy.api.PolicyEngine; + + public class GetConfigSample { + + public static void main(String[] args) throws Exception { + PolicyEngine pe = new PolicyEngine("config.properties"); + ConfigRequestParameters configRequestParams = new ConfigRequestParameters(); + configRequestParams.setPolicyName(".*"); + Collection configs = pe.getConfig(configRequestParams); + for (PolicyConfig config: configs){ + System.out.println(config.getPolicyConfigMessage()); + System.out.println(config.getPolicyConfigStatus()); + } + } + } + + + .. code-block:: java + :caption: Create Config FIrewall Policy Example + :linenos: + + package org.onap.policyEngine; + + import java.io.File; + import java.io.FileInputStream; + import java.io.FileNotFoundException; + import java.io.IOException; + import java.io.InputStream; + import java.io.StringReader; + import java.nio.file.Path; + import java.nio.file.Paths; + import java.text.SimpleDateFormat; + import java.util.Date; + import java.util.UUID; + + import javax.json.Json; + import javax.json.JsonObject; + import javax.json.JsonReader; + + import org.onap.policy.api.PolicyChangeResponse; + import org.onap.policy.api.PolicyConfigType; + import org.onap.policy.api.PolicyEngine; + import org.onap.policy.api.PolicyParameters; + import org.onap.policy.api.PolicyType; + + public class ConfigFirewallPolicyClient { + static Boolean isEdit = false; + public static void main(String[] args) { + try{ + PolicyEngine policyEngine = new PolicyEngine("config.properties"); + PolicyParameters policyParameters = new PolicyParameters(); + // Set Policy Type + policyParameters.setPolicyConfigType(PolicyConfigType.Firewall); //required + policyParameters.setPolicyName("MikeAPItesting.testConfigFirewallPolicy1607_1"); //required + //policyParameters.setPolicyScope("MikeAPItesting"); + //Directory will be created where the Policies are saved... this displays a subscope on the GUI + policyParameters.setRequestID(UUID.randomUUID()); + + // Set Safe Policy value for Risk Type + SimpleDateFormat dateformat3 = new SimpleDateFormat("dd/MM/yyyy"); + Date date = dateformat3.parse("15/10/2016"); + policyParameters.setTtlDate(date); + // Set Safe Policy value for Guard + policyParameters.setGuard(true); + // Set Safe Policy value for Risk Level + policyParameters.setRiskLevel("5"); + // Set Safe Policy value for Risk Type + policyParameters.setRiskType("PROD"); + File jsonFile = null; + String jsonRuleList = null; + Path file = Paths.get("C:\\policyAPI\\firewallRulesJSON\\Config_FW_Sample.json"); + jsonFile = file.toFile(); + + //buildJSON(jsonFile, jsonRuleList); + policyParameters.setConfigBody(buildJSON(jsonFile, jsonRuleList).toString()); + policyParameters.setConfigBodyType(PolicyType.JSON); + // API method to create Policy or update policy + PolicyChangeResponse response = null; + if (!isEdit) { + response = policyEngine.createPolicy(policyParameters); + } else { + response = policyEngine.updatePolicy(policyParameters); + } + + if(response.getResponseCode()==200){ + System.out.println(response.getResponseMessage()); + System.out.println("Policy Created Successfully!"); + }else{ + System.out.println("Error! " + response.getResponseMessage()); + } + } catch (Exception e) { + System.err.println(e.getMessage()); + } + + } + + private static JsonObject buildJSON(File jsonInput, String jsonString) throws FileNotFoundException { + JsonObject json = null; + JsonReader jsonReader = null; + if (jsonString != null && jsonInput == null) { + StringReader in = null; + in = new StringReader(jsonString); + jsonReader = Json.createReader(in); + json = jsonReader.readObject(); + in.close(); + } else { + InputStream in = null; + in = new FileInputStream(jsonInput); + jsonReader = Json.createReader(in); + json = jsonReader.readObject(); + try { + in.close(); + } catch (IOException e) { + System.err.println("Exception Occured while closing input stream"+e); + } + } + jsonReader.close(); + return json; + } + + } + + .. code-block:: java + :caption: Sample JSON file - Config_FW_Sample.json + :linenos: + + { + "serviceTypeId": "/v0/firewall/pan", + "configName": "AFTTFwPolicy1Config", + "deploymentOption": { + "deployNow": false + }, + "securityZoneId": "cloudsite:dev1a", + "serviceGroups": [{ + "name": "SSH", + "description": "Ssh service entry in service list", + "type": "SERVICE", + "transportProtocol": "tcp", + "appProtocol": null, + "ports": "22" + }], + "addressGroups": [{ + "name": "CiscoVCE", + "description": "Destination CiscoCVE", + "members": [{ + "type": "SUBNET", + "value": "12.63.31.61/12" + }] + }, { + "name": "HOHOServers", + "description": "Source HOHOServers for first testing", + "members": [{ + "type": "SUBNET", + "value": "12.60.32.11/23" + }] + }], + "firewallRuleList": [{ + "position": "1", + "ruleName": "FWRuleHOHOServerToCiscoVCE", + "fromZones": ["UntrustedZoneCiscoCVEName"], + "toZones": ["TrustedZoneHOHOName"], + "negateSource": false, + "negateDestination": false, + "sourceList": [{ + "type": "REFERENCE", + "name": "HOHOServers" + }], + "destinationList": [{ + "type": "REFERENCE", + "name": "CiscoVCE" + }], + "sourceServices": [], + "destServices": [{ + "type": "REFERENCE", + "name": "SSH" + }], + "action": "accept", + "description": "FW rule for HOHO source to CiscoVCE destination", + "enabled": true, + "log": true + }] + } + + .. code-block:: java + :caption: Delete Policy Example + :linenos: + + package org.onap.policyEngine; + + import org.onap.policy.api.DeletePolicyCondition; + import org.onap.policy.api.DeletePolicyParameters; + import org.onap.policy.api.PolicyChangeResponse; + import org.onap.policy.api.PolicyEngine; + + public class DeletePolicyClient { + + public static void main(String[] args) { + try { + + PolicyEngine policyEngine = new PolicyEngine("config.properties"); + DeletePolicyParameters policyParameters = new DeletePolicyParameters(); + + //Parameter arguments + policyParameters.setPolicyName("MikeConsole.Config_testDeleteAPI6.1.xml"); + policyParameters.setPolicyComponent("PDP"); + policyParameters.setPdpGroup("default"); + policyParameters.setDeleteCondition(DeletePolicyCondition.ALL); + policyParameters.setRequestID(null); + + // API method to Push Policy to PDP + PolicyChangeResponse response = null; + response = policyEngine.deletePolicy(policyParameters); + + if(response.getResponseCode()==200){ + System.out.println(response.getResponseMessage()); + System.out.println("Policy Deleted Successfully!"); + }else{ + System.out.println("Error! " + response.getResponseMessage()); + } + + } catch (Exception e) { + System.err.println(e.getMessage()); + + } + } + } + + + .. code-block:: java + :caption: Push Policy Example + :linenos: + + package org.onap.policyEngine; + + import org.onap.policy.api.PolicyChangeResponse; + import org.onap.policy.api.PolicyEngine; + import org.onap.policy.api.PushPolicyParameters; + + public class PushPoliciesToPDP { + public static void main(String[] args) { + try { + + PolicyEngine policyEngine = new PolicyEngine("config.properties"); + PushPolicyParameters policyParameters = new PushPolicyParameters(); + + //Parameter arguments + policyParameters.setPolicyName("Mike.testCase1"); + policyParameters.setPolicyType("Base"); + //policyParameters.setPolicyScope("MikeAPItesting"); + policyParameters.setPdpGroup("default"); + policyParameters.setRequestID(null); + + // API method to Push Policy to PDP + PolicyChangeResponse response = null; + response = policyEngine.pushPolicy(policyParameters); + + if(response.getResponseCode()==204){ + System.out.println(response.getResponseMessage()); + System.out.println("Policy Pushed Successfully!"); + }else{ + System.out.println("Error! " + response.getResponseMessage()); + } + + } catch (Exception e) { + System.err.println(e.getMessage()); + + } + } + } + + + .. code-block:: java + :caption: Decision Policy Example + :linenos: + + package org.onap.policyEngine; + + import java.util.Arrays; + import java.util.HashMap; + import java.util.LinkedList; + import java.util.List; + import java.util.Map; + import java.util.UUID; + + import org.onap.policy.api.AttributeType; + import org.onap.policy.api.PolicyChangeResponse; + import org.onap.policy.api.PolicyClass; + import org.onap.policy.api.PolicyEngine; + import org.onap.policy.api.PolicyParameters; + + public class DecisionPolicyClient { + static Boolean isEdit = true; + public static void main(String[] args) { + try { + PolicyEngine policyEngine = new PolicyEngine("config.properties"); + PolicyParameters policyParameters = new PolicyParameters(); + // Set Policy Type + policyParameters.setPolicyClass(PolicyClass.Decision); //required + policyParameters.setPolicyName("MikeAPItests.testDecisionAPI"); //required + policyParameters.setOnapName("java"); //required + policyParameters.setPolicyDescription("This is a sample Decision policy UPDATE example with Settings"); //optional + //policyParameters.setPolicyScope("MikeAPItests"); + //Directory will be created where the Policies are saved... this + displays a a subscope on the GUI + + //Set the Component Attributes... These are Optional + Map configAttributes = new HashMap<>(); + configAttributes.put("Template", "UpdateTemplate"); + configAttributes.put("controller", "default"); + configAttributes.put("SamPoll", "30"); + configAttributes.put("value", "abcd"); + + Map> attributes = new HashMap<>(); + attributes.put(AttributeType.MATCHING, configAttributes); + + //Set the settings... These are Optional + Map settingsMap = new HashMap<>(); + settingsMap.put("server", "5"); + + attributes.put(AttributeType.SETTINGS, settingsMap); + policyParameters.setAttributes(attributes); + + + List dynamicRuleAlgorithmLabels = new LinkedList<>(); + List dynamicRuleAlgorithmFunctions = new LinkedList<>(); + List dynamicRuleAlgorithmField1 = new LinkedList<>(); + List dynamicRuleAlgorithmField2 = new LinkedList<>(); + + //Example of a complex Rule algorithm using the settings in the Field1 + /* label field1 function field2 + * ***************************************************** + * A1 S_server integer-equal 90 + * A2 cap string-contains ca + * A3 cobal integer-equal 90 + * A4 A2 and A3 + * A5 Config integer-greater-than 45 + * A6 A4 ` or A5 + * A7 A1 and A6 + */ + dynamicRuleAlgorithmLabels = Arrays.asList("A1","A2","A3","A4","A5","A6","A7"); + dynamicRuleAlgorithmField1 = Arrays.asList("S_server","cap","cobal","A2","Config","A4","A1"); + dynamicRuleAlgorithmFunctions = Arrays.asList("integer-equal","string-contains","integer-equal","and","integer-greater-than","or","and"); + dynamicRuleAlgorithmField2 = Arrays.asList("90","ca","90","A3","45","A5","A6"); + + policyParameters.setDynamicRuleAlgorithmLabels(dynamicRuleAlgorithmLabels); + policyParameters.setDynamicRuleAlgorithmField1(dynamicRuleAlgorithmField1); + policyParameters.setDynamicRuleAlgorithmFunctions(dynamicRuleAlgorithmFunctions); + policyParameters.setDynamicRuleAlgorithmField2(dynamicRuleAlgorithmField2); + + policyParameters.setRequestID(UUID.randomUUID()); + + // API method to create Policy or update policy + PolicyChangeResponse response = null; + if (!isEdit) { + response = policyEngine.createPolicy(policyParameters); + } else { + response = policyEngine.updatePolicy(policyParameters); + } + + if(response.getResponseCode()==200){ + System.out.println(response.getResponseMessage()); + System.out.println("Policy Created Successfully!"); + }else{ + System.out.println("Error! " + response.getResponseMessage()); + } + } catch (Exception e) { + System.err.println(e.getMessage()); + } + } + } + + + .. code-block:: java + :caption: List Config Policy Example + :linenos: + + package org.onap.policyEngine; + + import java.util.Collection; + import java.util.HashMap; + import java.util.Map; + import java.util.UUID; + + import org.onap.policy.api.ConfigRequestParameters; + import org.onap.policy.api.PolicyConfigException; + import org.onap.policy.api.PolicyEngine; + import org.onap.policy.api.PolicyEngineException; + import org.onap.policy.common.logging.flexlogger.FlexLogger; + import org.onap.policy.common.logging.flexlogger.Logger; + + public class ListConfigPoliciesClient { + + private static final Logger LOGGER = FlexLogger.getLogger(ListConfigPoliciesClient.class); + + public static void main(String[] args) { + PolicyEngine policyEngine; + + // List Config Policies Example + try { + policyEngine = new PolicyEngine("config.properties"); + ConfigRequestParameters parameters = new ConfigRequestParameters(); + + parameters.setPolicyName(".*"); + parameters.setOnapName(".*"); + parameters.setConfigName(".*"); + + Map configAttributes = new HashMap<>(); + configAttributes.put("java", "java"); + configAttributes.put("peach", "Tar"); + configAttributes.put("true", "false"); + configAttributes.put("small", "testPass"); + parameters.setConfigAttributes(configAttributes); + + parameters.setRequestID(UUID.randomUUID()); + + Collection response = policyEngine.listConfig(parameters); + if(response!=null && !response.contains("PE300")){ + for(String configList : response){ + System.out.println(configList.toString()+"\n"); + } + }else{ + System.out.println("Error! " +response); + } + + } catch (PolicyConfigException e) { + LOGGER.error("Exception Occured"+e); + } catch (PolicyEngineException e) { + LOGGER.error("Exception Occured"+e); + } + } + } + + +**JSON EXAMPLES** + + .. code-block:: java + :caption: Create Microservice Policy + :linenos: + + API: createPolicy + OPERATION: PUT + REQUEST BODY: + { + "configBody": "{ + \"service\":\"ControllerServiceSampleSdnlServiceInstance\", + \"location\":\"Edge\", + \"uuid\":\"TestUUID\", + \"policyName\":\"testRestCreateMicroServicesNewParams\", + \"description\":\"testing Create\", + \"configName\":\"TestName\", + \"templateVersion\":\"1604\", + \"priority\":\"4\", + \"version\":\"0.1.0-SNAPSHOT\", + \"policyScope\":\"resource=F5,service=vSCP,type=configuration,closedLoopControlName=vSCP_F5_Firewall_d925ed73-8231-4d02-9545-db4e101f88f8\", + \"content\":{ + \"taskOrchestratedConfiguration\":\"test\", + \"taskCustomConfiguration\":\"set\", + \"configuration\":\"test\", + \"cdapUrl\":\"testurl\", + \"taskName\":\"test\", + \"taskNameTEST\":\"TEST\", + \"users\":\"[tuser]\", + \"adminUsers\":\"[lji]\", + \"taskConfigFilePath\":\"test\", + \"managerPortNumber\":\"999\", + \"taskType\":\"test\", + \"taskCommandFilePath\":\"tset\", + \"contailIp\":\"test\", + \"consoleUsers\":\"[odu-e2e]\", + \"taskStatusFilePath\":\"test\" + } + }", + "policyConfigType": "MicroService", + "policyName": "MikeAPITesting.testRestCreateMicroServicesNewParams", + "ecompName": "SDNC" + } + + + .. code-block:: java + :caption: Update Microservice Policy + :linenos: + + API: updatePolicy + OPERATION: PUT + REQUEST BODY: + { + "configBody": "{ + \"service\":\"ControllerServiceSampleSdnlServiceInstance\", + \"location\":\"Edge\", + \"uuid\":\"TestUUID\", + \"policyName\":\"testRestCreateMicroServicesNewParams\", + \"description\":\"testing Update\", + \"configName\":\"TestName\", + \"templateVersion\":\"1604\", + \"priority\":\"4\", + \"version\":\"0.1.0-SNAPSHOT\", + \"policyScope\":\"resource=F5,service=vSCP,type=configuration,closedLoopControlName=vSCP_F5_Firewall_d925ed73-8231-4d02-9545-db4e101f88f8\", + \"content\":{ + \"taskOrchestratedConfiguration\":\"test\", + \"taskCustomConfiguration\":\"set\", + \"configuration\":\"test\", + \"cdapUrl\":\"testurl\", + \"taskName\":\"test\", + \"taskNameTEST\":\"TEST\", + \"users\":\"[tuser]\", + \"adminUsers\":\"[lji]\", + \"taskConfigFilePath\":\"test\", + \"managerPortNumber\":\"999\", + \"taskType\":\"test\", + \"taskCommandFilePath\":\"tset\", + \"contailIp\":\"test\", + \"consoleUsers\":\"[odu-e2e]\", + \"taskStatusFilePath\":\"test\" + } + }", + "policyConfigType": "MicroService", + "policyName": "MikeAPITesting.testRestUpdateMicroServicesNewParams", + "ecompName": "SDNC" + } + + +**CURL EXAMPLES** + + .. code-block:: bash + :caption: Push Policy + + echo "pushPolicy : PUT : com.vLoadBalancer" + echo "pushPolicy : PUT : com.vLoadBalancer" + curl -v --silent -X PUT --header 'Content-Type: application/json' --header 'Accept: text/plain' --header 'ClientAuth: XYZ' --header 'Authorization: Basic XYZ' --header 'Environment: TEST' -d '{ + "pdpGroup": "default", + "policyName": "com.vLoadBalancer", + "policyType": "MicroService" + }' 'http://pdp:8081/pdp/api/pushPolicy' + + + .. code-block:: bash + :caption: Delete Policy + + echo "deletePolicy : DELETE : com.vFirewall" + curl -v --silent -X DELETE --header 'Content-Type: application/json' --header 'Accept: text/plain' --header 'ClientAuth: XYZ' --header 'Authorization: Basic XYZ' --header 'Environment: TEST' -d '{ + "pdpGroup": "default", + "policyComponent": "PDP", + "policyName": "com.vFirewall", + "policyType": "MicroService" + }' 'http://pdp:8081/pdp/api/deletePolicy' + + + .. code-block:: bash + :caption: Get Config + + echo "Get all Config Policy example" + curl -i -v -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'ClientAuth: XYZ' -H 'Authorization: Basic XYZ -H 'Environment: TEST' -X POST -d '{ + "policyName": ".*" + }' http://${PDP_IP}:8081/pdp/api/getConfig + + +**ADDITIONAL EXAMPLES** + + .. code-block:: bash + :caption: Deleting a Policy from PAP + + // Deleting from PAP will remove the policy from the PolicyEntity & PolicyVersion tables (UI-Editor tab). + // This means that the policy is no longer be available in Policy System. + + // PayLoad: + { "policyName": "com.testpolicy", //scope.policyName + "policyType": "Base", //policy type + "policyComponent": "PAP", //component name + "deleteCondition": "ALL" //versions (ALL or CURRENT) + } + + + .. code-block:: bash + :caption: Deleting a Policy from PDP + + // Deleting from PDP will delete the policy from the PDP Group. The policy is still available in Policy System. + // When the policy is needed again, the policy should be pushed to the PDP. + + // PayLoad: + { "policyName": "com.testpolicy", //scope.policyName + "policyType": "Base", //policy type + "policyComponent": "PDP", //component name + "pdpGroup": "Default" //group name + } + Additional Information ^^^^^^^^^^^^^^^^^^^^^^ -- 2.16.6