API Doc: Add examples
API Doc: Add examples
-------------------------------------------------------------
Change-Id: Ia219b06cdb05ef67c40c8920ea05087a0bf249d8
Issue-ID: POLICY-1219
Signed-off-by: Saryu Shah <ss3917@att.com>
diff --git a/docs/platform/offeredapis.rst b/docs/platform/offeredapis.rst
index 811a128..4a76fb7 100644
--- a/docs/platform/offeredapis.rst
+++ b/docs/platform/offeredapis.rst
@@ -33,6 +33,606 @@
.. 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<PolicyConfig> 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<String, String> configAttributes = new HashMap<>();
+ configAttributes.put("Template", "UpdateTemplate");
+ configAttributes.put("controller", "default");
+ configAttributes.put("SamPoll", "30");
+ configAttributes.put("value", "abcd");
+
+ Map<AttributeType, Map<String,String>> attributes = new HashMap<>();
+ attributes.put(AttributeType.MATCHING, configAttributes);
+
+ //Set the settings... These are Optional
+ Map<String, String> settingsMap = new HashMap<>();
+ settingsMap.put("server", "5");
+
+ attributes.put(AttributeType.SETTINGS, settingsMap);
+ policyParameters.setAttributes(attributes);
+
+
+ List<String> dynamicRuleAlgorithmLabels = new LinkedList<>();
+ List<String> dynamicRuleAlgorithmFunctions = new LinkedList<>();
+ List<String> dynamicRuleAlgorithmField1 = new LinkedList<>();
+ List<String> 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<String, String> 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<String> 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
^^^^^^^^^^^^^^^^^^^^^^