Java Library Wrapper for Admin API

Example:

Java Library Wrapper that uses Split Admin REST API to allow creating, updating and deleting feature flags as part of automation workflow. Reference to Split Admin API can be found here: https://docs.split.io/reference

Environment:

• Java 1.8

• Apache Httpclient 4.5.2

• slf4j-log4j12 1.7.21

• Google json-simple 1.1.1

• Snakeyaml 1.26

• Google Guava r05

How to use:

• Class wrapper for Admin API  is:

         SplitAPI.java

• To initialize the API library, pass the Admin API Key as follows:

SplitAPI spAdmin = new SplitAPI("ADMIN API KEY");

•  Library will throw AssertionError exception if the HTTP return code is anything other than 200, 202 and 302
• If the Admin API call return code is 429 (throttled), the plugin will sleep for 5 seconds then retry the request, max retired are capped at 10.

Functions Reference:

String GetWorkspaceId(String workspaceName)

The function take workspace name and return the internal id, the workspace id is required for most API Calls.

String workspaceId = spAdmin.GetWorkspaceId("Default");
System.out.println("WorkspaceId: "+workspaceId);

int CreateSplit(String workspaceId, String trafficTypeName, String splitName, String description)

Function to create new feature flag given workspace id, flag name, traffic type and description, function will ignore the task if the feature flag already exist in the workspace, otherwise will return the http code returned by the API request.

spAdmin.CreateSplit(workspaceId, "user", "split-name", "description for the feature flag");

int AddSplitToEnvironment(String workspaceId, String environmentName, String splitName, String definition)

Function to add a feature flag to an environment, specifying the definitions (treatments, allowlists, targeting rules, etc.) as JSON structure accepted by Split Admin API, see the API reference for more info: https://docs.split.io/reference#create-split-definition-in-environment, will return the http code returned by the API request.

// Split with two treatments on/off, set default rule to 100% off
String splitDefinition="{\"treatments\":[{\"name\": \"on\", \"description\": \"\"}, {\"name\": \"off\", \"description\": \"\"}],\"defaultTreatment\":\"off\",\"rules\":[], \"defaultRule\":[{\"treatment\": \"off\", \"size\": 100}]}";
spAdmin.AddSplitToEnvironment(workspaceId, "Production", "split-name", splitDefinition);

int AddAllowListToSplit(String workspaceId, String environmentName, String splitName, String treatmentName, String allowlistKey)

Function to add a user key to allowlist section for given feature flag. Only one key can be added. Will return the http code returned by the API request.

spAdmin.AddAllowListToSplit(workspaceId, "Production", "split-name", "on", "key1");

String GetSplitDefinition(String workspaceId, String splitName, String environmentName)

Function to get flags definitions for a specific feature flag in an environment, definitions include treatments, dynamic configurations, targeting rules, default rule and default treatment.

The definition is returned as JSON structure format according to API reference, for more info: https://docs.split.io/reference#create-split-definition-in-environment

String definitions = GetSplitDefinition(workspaceId, "split-name",  "Production");
System.out.println("Split Definitions: " + definitions);

String GetSplitsList(String workspaceId)

Function to fetch list of feature flags in a given workspace. Returns a JSON structure with Split lists based on the API reference: https://docs.split.io/reference#list-splits

String resp = GetSplitsList(workspaceId);
JSONParser parser = new JSONParser();
Object obj = parser.parse(resp);
JSONObject js = (JSONObject) obj;
JSONArray jsArray = (JSONArray)js.get("objects");
System.out.println("Split List: ");
for (int ws = 0; ws < jsArray.size(); ws++) {
   JSONObject jsItem = (JSONObject) jsArray.get(ws);
   System.out.println(jsItem.get("name").toString());
}

String GetSplitsInEnvironmentList(String workspaceId, String environmentName)

Function to fetch list of feature flags in a given environment. Returns a JSON structure with Split lists based on the API reference: https://docs.split.io/reference#lists-split-definitions-in-environment

String resp = GetSplitsInEnvironmentList(workspaceId, "Production");
JSONParser parser = new JSONParser();
Object obj = parser.parse(resp);
JSONObject js = (JSONObject) obj;
JSONArray jsArray = (JSONArray)js.get("objects");
System.out.println("Split names: ");
for (int ws = 0; ws < jsArray.size(); ws++) {
    JSONObject jsItem = (JSONObject) jsArray.get(ws);
    System.out.println(jsItem.get("name").toString());
}

int DeleteSplitDefinition(String workspaceId, String environmentName, String splitName)

Function to delete existing feature flag definition from given environment, function will ignore the task if split definitions does not exist in the environment, otherwise will return the http code returned by the API request.

spAdmin.DeleteSplitDefinition(workspaceId, "Production", "split-name");

int KillSplit(String workspaceId, String environmentName, String splitName)

Function to perform Kill operation for a given feature flag in an environment. Will return the http code returned by the API request.

spAdmin.KillSplit(workspaceId, "Production", "split-name");

int DeleteSplit(String workspaceId, String splitName)

Function to delete existing feature flag given workspace, function will ignore the task if split does not exist in the workspace, otherwise will return the http code returned by the API request.

The API will fail if the feature flag has definitions in environment(s), delete the definition first before deleting the feature flag.

spAdmin.DeleteSplit(workspaceId, "split-name");

int CreateSplitFromYAML(String workspaceId, String environmentName, String trafficTypeName, String YAMLFile)

This function will read a given YAML file populated with feature flags containing treatments, allowlisted keys, dynamic configs and percentages for default rule, see YAML format below. It will check if the feature flag and flags definitions exists in the given workspace/environment, if not, the subtask is skipped, will return the http code returned by the API request. 
Note: If there are missing fields for feature flags in the YAML file, the function will attempt to complete the definitions automatically, see examples below.

YAML format:

- split_name:
    treatment: "treatment_applied_to_this_entry"
    keys: "single_key_or_list"
    percentage: "integer between (0-100)"

Examples

1- Feature flag below has 3 treatments (on/off/unallocated), only "on" treatment contains allowlisted id "key1". For default rule, "on" is set to 80%, "off" is set to 10%, the plugin will assign the last 10% to "unallocated" treatment.

- percentage_less_100_flag:
    treatment: "on"
    keys: ["key1"]
    percentage: "80"
- percentage_less_100_flag:
    treatment: "off"
    percentage: "10"
- percentage_less_100_flag:
    treatment: "unallocated"

2- Feature flag below contains only treatments, no percentages specified for default rule, the plugin will set the first treatment to 100% for default rule.

- no_rule_flag:
    treatment: "on"
- no_rule_flag:
    treatment: "off"

3- Feature flag below contains only one treatments, no percentages specified for default rule, the plugin will add second treatment with name "SecondTreatment", and set the first treatment to 100% for default rule.

- one_treatment_flag:
    treatment: "one"

4- Feature flag below has two treatments with their dynamic configs, treatment "off" has two keys in allowlist section, default rule has only "on" treatment set to 50%, the plugin will add "off" with 50%.

- correct_data_flag:
    treatment: "on"
    config: "this applies only to ON treatment"
    percentage: "50"
- correct_data_flag:
    treatment: "off"
    keys: ["key1", "key2"]
    config: "this applies only to OFF treatment"

5- Feature flag below only has the name, no other information is given, the plugin will add "on" and "off" treatments, and set default rule to "off" with 100%

- no_treatment_flag:

 

Download Link