1. Split Help Center
  2. Integrate & automate
  3. Best Practices

Creating, editing, and deleting feature flags using Admin API

  • Updated

Use the Split administration API is a tool to create, edit, and delete feature flags via HTTP based API calls. This allows you to manage feature flags and control their rollout from an external system instead of using the user interface.

You may want to do this if you are building a management console for internal product SME users to do their own configuration and management of feature flags, or possibly some simple automation of feature flags for a workflow.

Prerequisites

To run these API calls, there are a few pieces of information that will be needed. 

  • Download cURL. This application is a free HTTP API client that we will use to make API calls in this document. It should be installed already if you are on a Mac or a Linux machine. If you are more comfortable with other ways to call HTTP endpoints or other HTTP clients, you should be able to follow along. It is a command line tool, so you need to have basic familiarity with the CMD.exe command prompt on Windows or Terminal emulators on Mac or Linux machines.
  • Get the organization ID of your Split organization. You can retrieve that from the first string that comes after split.io/org/ in the URL you see in your url bar once you are logged in to Split.

org_id.png
The organization ID is what’s in the blue box. Keep this handy as you will need it to drill down to the data in the workspaces and environments that will be used for creating, editing, and deleting feature flags in this document. 

  • You need to create an Admin API key. You can create this by navigating to the Admin Settings, select Workspace settings, and then API keys. Click the Action button and from the menu list, select Create API key in the top right. The following page displays:

select-admin-api-key.png

Select Admin as this tutorial’s API key needs to be for the Admin API. Give it a name and optionally restrict it to environments and workspaces that you are using the API key for. Once you click Create an API key is available for use:

new-admin-api-key-list.png

Now that you’ve gotten an API key and the Organization ID, let’s get to creating, editing, and deleting feature flags.

Note: For this document, we are using $orgId and $apiKey to replace the actual API key and organization ID that we gathered previously. Please replace these with what you have copied down from this Prerequisites section as the organization ID and API key.

Creating a feature flag

Creating a feature flag is fundamental to using Split. There are a few steps to doing this via the Admin API. Feature flags exist in a single workspace and have targeting rules that can be modified on a per environment basis. So to create a feature flag, you need to first determine which workspace within your organization you are creating the feature flag in. To get your list of workspaces, you can use cURL with this command:

curl --location --request GET 'https://api.split.io/internal/api/v2/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey

This returns a list of workspaces and their corresponding workspace IDs: 

{
"objects": [
 {
  "name": "Default",
  "type": "workspace",
  "id": "id-default-workspace-UUID",
  "requiresTitleAndComments": false
  },
  {
   "name": "client-team",
   "type": "workspace",
   "id": "id-client-workspace-UUID",
   "requiresTitleAndComments": false
   },
   {
    "name": "server-team",
    "type": "workspace",
    "id": "id-server–workspace-UUID",
    "requiresTitleAndComments": false
   }
 ],
 "offset": 0,
 "limit": 10,
 "totalCount": 3
}

Let’s say you want to create a feature flag in the Default workspace. So store the id for that workspace, id-default-workspace-UUID. Now, to create your feature flag , you can call the POST api for creating feature flags. 

Start by creating a feature flag our_new_split_name and we can give it a description as description of what this new split does. This feature flag is using the trafficType of user. 

The following curl command creates this feature flag:

curl --location --request POST 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/trafficTypes/user/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey' \
--data-raw '{
  "name": "our_new_split_name",
  "description": "Description of what this new split does"
}'

Note: The name and description are part of the JSON body of the curl command. The string user that defines the trafficType is part of the endpoint being called out to. 

The return value from calling this command is the following:

{
 "id": "id-split-UUID",
 "name": "our_new_split_name",
 "description": "Description of what this new split does",
 "trafficType": {
  "id": "id-user-trafficType-UUID",
  "name": "user"
},
 "creationTime": 1645214274838,
 "rolloutStatus": {
   "id": "id-preprod–rolloutStatus-UUID",
   "name": "Pre-Production"
},
 "rolloutStatusTimestamp": 1645214274838,
 "tags": null
}

Note: You need the feature flag’s id, id-split-UUID, in order to make modifications to the feature flag, so keep track of this id as we move to the next section.

The default rolloutStatus for a feature flag is Pre-Production. Also note that this feature flag has no targeting rules in any environment as we have not defined any. 

feature-flag-using-admin-api.png

Editing a feature flag

If you are managing configuration of feature flags from your own tool, or programmatically through automation you inevitably need to edit feature flags. In this section, we discuss what is included in the API to edit and make modifications to feature flags.

Our feature flag in the last section was created in the proper workspace, but without targeting rules, it can’t be used. Targeting rules exist only in a single environment so you need to get the list of environments for the workspace. To get the list of environments, run the following curl command:

curl --location --request GET 'https://api.split.io/internal/api/v2/environments/ws/id-default-workspace-UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey

The response is  similar to the following:

[
 {
  "name": "Prod-Default",
  "id": "id-prodEnv-UUID",
   "production": true
 },
 {
  "name": "Staging-Default",
  "id": "id-stgEnv-UUID",
  "production": false
 }
]

Note: This response is a JSON array at the root level of the response body, not an object containing an array.

For example, let’s say we want to create targeting rules in the staging environment. So we need to store the id-stgEnv-UUIDfor later processing. Let’s get the configuration of our existing feature flag to see what the configuration currently looks like from the API perspective. 

curl --location --request GET 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/id-split-UUID/environments/id-stgEnv-UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey' \
--data-raw ''

We get a 404 response, stating the feature flag definition does not exist in the environment. 

{
 "code": 404,
 "message": "Could not find splitmetadata id-split-UUID",
 "details": "",
 "transactionId": "22f0rxo8uno"
}

This is an important item to note. Feature flags exist at a workspace level but their definition, including targeting rules, exist individually in each feature flag environment. Colloquially, the environment level feature flag is referred to as a meta- feature flag. The rollout status, feature flag name, traffic type, tags, description, and feature flag owners exist at the workspace level. The rest of the feature flag  is defined per environment. 

So now let’s talk about the configuration we want to add to our feature flag. The feature flag configuration is passed via the API in the body of the HTTP API request. To build this, we need the UUID identifiers for the feature flag, the environment, and the traffic type. These are bolded below. Additionally, we have given this feature flag two treatments: On, and Off. It is rolled out 100%. The employees segment gets the On treatment, all other users get 50/50 randomized on or off. 

{
 "id": "id-split-UUID",
 "name": "our_new_split_name",
 "environment": {
  "id": "id-stgEnv-UUID",
  "name": "Staging-Default"
 },
  "trafficType": {
   "id": "id-user-trafficType-UUID",
   "name": "user"
 },
 "killed": false,
 "treatments": [
    {
     "name": "on",
     "description": "feature is on"
    },
    {
     "name": "off",
     "description": "feature is off"
    }
  ],
  "defaultTreatment": "off",
  "baselineTreatment": "off",
  "trafficAllocation": 100,
  "rules": [
    {
     "buckets": [
       {
         "treatment": "on",
         "size": 100
       }
      ],
      "condition": {
        "combiner": "AND",
        "matchers": [
          {
           "type": "IN_SEGMENT",
           "string": "employees"
          }
        ]
      }
     }
  ],
  "defaultRule": [
    {
      "treatment": "on",
      "size": 50
    },
    {
     "treatment": "off",
      "size": 50
    }
   ]
  }

We can send this configuration to Split using cURL in this way, with the configuration passed in as raw data:

Note: The body of the message in the –data-raw parameter must be enclosed in single straight quotes.

curl --location --request POST 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/our_new_split_name/environments/id-stgEnv-UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey \
--data-raw ' {
     "id": "id-split-UUID",
     "name": "our_new_split_name",
     "environment": {
       "id": "id-stgEnv-UUID",
       "name": "Staging-Default"
     },
     "trafficType": {
       "id": "id-user-trafficType-UUID",
       "name": "user"
     },
     "killed": false,
     "treatments": [
       {
         "name": "on",
         "description": "feature is on"
       },
       {
         "name": "off",
         "description": "feature is off"
        }
     ],
     "defaultTreatment": "off",
     "baselineTreatment": "off",
     "trafficAllocation": 100,
     "rules": [
       {
         "buckets": [
           {
            "treatment": "on",
            "size": 100
           }
       ],
         "condition": {
           "combiner": "AND",
           "matchers": [
            {
              "type": "IN_SEGMENT",
              "string": "employees"
             }
          ]
        }
      }
    ],
    "defaultRule": [
      {
       "treatment": "on",
       "size": 50
      },
      {
       "treatment": "off",
        "size": 50
      }
    ]
  }
'

You should get a response confirming the response successfully was accepted by the endpoint. It mirrors back the configuration that you sent with 2 additional pieces of information at the end, a creationTime and a lastUpdateTime. 

{
  "id": "id-split-UUID",
  "name": "our_new_split_name",
  "environment": {
   "id": "id-stgEnv-UUID",
   "name": "Staging-Default"
},
  "trafficType": {
   "id": "id-user-trafficType-UUID",
   "name": "user"
},
  "killed": false,
  "treatments": [
    {
     "name": "on",
     "description": "feature is on"
    },
    {
     "name": "off",
     "description": "feature is off"
    }
 ],
 "defaultTreatment": "off",
 "baselineTreatment": "off",
 "trafficAllocation": 100,
 "rules": [
   {
    "buckets": [
      {
       "treatment": "on",
       "size": 100
      }
 ],
 "condition": {
   "combiner": "AND",
   "matchers": [
     {
       "type": "IN_SEGMENT",
       "string": "employees"
      }
    ]
   }
  }
 ],
 "defaultRule": [
   {
     "treatment": "on",
     "size": 50
   },
   {
     "treatment": "off",
     "size": 50
    }
 ],
 "creationTime": 1645220815555,
 "lastUpdateTime": 1645220815555
}

Now if you go into the Split user interface, you should see the feature flag definition. 

set-treatments.png

target-specific-subset.png

After we’ve added that to the feature flag definition, let’s say we want to increase the randomization from 50/50 on/off to 80/20 on off, as we’re fairly confident in the feature. 

Note: More information on the components of a Split’s JSON definition can be found : https://docs.split.io/reference/split-definition.

We do not have to build that JSON definition again. We can call the feature flags endpoint with a PATCH request to just update what we want to. Review the following command. Note that we are defining an op (operation) to perform. It can be either replace, add, or remove. We are also defining a path in the JSON of the feature flag to perform the operation. In this case we are replacing the defaultRule with one that defines an 80/20 randomization as opposed to a 50/50 one.

 

curl --location --request PATCH 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/our_new_split_name/environments/id-stgEnv-UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey \
--data-raw '[{"op": "replace", "path": "/defaultRule", "value":[
   {
     "treatment": "on",
     "size": 80
   },
   {
    "treatment": "off",
    "size": 20
   }
   ]}]'

If we log in to the Split user interface, we can see the rollout updated. 

default-rule.png

Updating the description, tags, or rollout status requires a different endpoint. Let’s say we want to update this to have the status Ramping now because you’re working on ramping up the feature rollout percentage. Currently it is in Pre-Release. 

First we have to get the list of rollout statuses. You can do that with this command:

curl --location --request GET 'https://api.split.io/internal/api/v2/rolloutStatuses?wsId=id-default-workspace-UUID' \
--header 'Authorization: Bearer $apiKey

The response shows the list of all rollout statuses in a JSON array:

[
 ……
  {
   "id": "id-ramping-UUID",
   "name": "Ramping",
   "description": "Splits that are turned on for a small percentage of users to make sure no performance issues or larger issues come up"
  },
  {
   "id": "id-experimenting-UUID",
   "name": "Experimenting",
   "description": "Splits that have are ramped for max power in an experiment to get results as quickly as possible"
  },
  …
]

With this, now we have the id for the ramping rollout status, and can call a command to update your feature flag. This is a patch command as well, so note that you are replacing the rolloutStatus/id from the workspace-wide feature flag JSON that was created in the previous section, Creating a Feature Flag. 

curl --location --request PATCH 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/our_new_split_name' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey \
--data-raw '[
   {
     "op":"replace",
     "path":"/rolloutStatus/id",
     "value":"id-ramping-UUID"
   }
]'
The result should be the following:
{
 "id": "id-split-UUID",
 "name": "our_new_split_name",
 "description": "Description of what this new split does",
 "trafficType": {
   "id": "id-user-trafficType-UUID",
   "name": "user"
 },
 "creationTime": 1645214274838,
 "rolloutStatus": {
   "id": "id-ramping-UUID",
   "name": "Ramping"
 },
 "rolloutStatusTimestamp": 1645223192008,
 "tags": null
}

You can see the updated rollout status upon logging in to the user interface: 

updated_status.png

Note: Killing a feature flag is more than just updating the rollout status. To kill a feature flag, you have to call the specific Kill endpoint. For more information, refer to the Kill a split in environment API. 

Deleting a feature flag

Finally, let’s say you’ve moved the feature flag up to rollout at 100% and have removed it from your codebase. You’ve successfully rolled out a new feature. Congratulations! Now it’s time to remove the feature flag from the Split user interface. Individual feature flag definitions can be deleted on an environment by environment basis using this endpoint:

curl --location --request DELETE 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/our_new_split_name/environments/id-stgEnv-UUID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey \
--data-raw ''

The request returns true with no other information to denote a successful deletion

You can also delete the workspace wide feature flag using the following endpoint. For most cases this should be sufficient, as it will also remove the feature flag definitions in the workspace environments. 

curl --location --request DELETE 'https://api.split.io/internal/api/v2/splits/ws/id-default-workspace-UUID/our_new_split_name' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $apiKey \
--data-raw ''

Similarly, this request also returns true when a feature flag is successfully deleted.

If you try to navigate to your feature flag in the Split user interface, you get an error message because this feature flag no longer exists. 

External references

For more information, refer to the the Splits section of the API Guide .

There are also wrappers for multiple programming languages that have already been built for your convenience. Refer to the API wrappers examples for more information.

A Postman API collection for the public Admin API endpoints is available for those who are interested in using the free Postman tool for API testing and development.

Related articles

Comments

0 comments

Please sign in to leave a comment.