Running Split SDK in Localhost Mode From JSON

With travel picking up again, Split is keeping up the pace by rapidly releasing localhost mode from JSON support in three server-side SDKs: Java, Go, and Python. This feature was added specifically in response to customer requests. It is indispensable when you wish to develop code productively over internet intermittencies and while on the move.

In fact, these very words you are skimming are also in motion, uploaded en route to a unique South American waterfall shared by two countries. I'll wait here while you flip to a quick internet search to find it… Alright, now that your curiosity is satisfied, let's continue.

With new digital nomad visas opening up, and travel restrictions closing down, there is no time like the present to take advantage of Split's localhost mode from JSON. It supports retrieving complete Split environment definitions from Split Cloud in JSON format and then working offline from the local JSON files. This article will show you how it's done.

You will first need to download your Split rules and then point your Split SDK instance to your local files. Lastly, you will see how Split SDK cleverly pulls changes from your local JSON files, just as it normally would from the Cloud.

Downloading Split Rules

We retrieve the definitions (feature flag definitions, called splits, and lists of users, called segments) using two convenient GET requests, as shown below.

Utilizing curl on the command line, we send a request to Split’s REST API that returns the JSON representation of the split (feature flag) definitions. You can see the command line request below, together with a screenshot of a sample response.

curl -XGET -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" https://sdk.split.io/api/splitChanges\?since\=-1

A few things of note: The Split REST API base URL is https://sdk.split.io/api. Then endpoint splitChanges will return splits (feature flags). Finally, the query parameter since can be used to specify a number that identifies the previously synced version (this is the till JSON parameter shown in the code above).

The idea behind since is to optimize response size, allowing only the delta (differences) to be returned. In our case, we pass -1 as the value of this parameter to override the optimization and prompt the API to return the entire set of split definitions. Of course, the YOUR_API_KEY is a placeholder for your own API key that you retrieve from the Split Management Console.

Lastly, you will notice a segmentName value in the above JSON response. The Split SDK will look for this segment to identify the users for which the split (feature flag) definition applies. We will also retrieve the JSON representation of each segment definition (in this example, there is only one) from Split's REST API using the segmentChanges/{segment_name} endpoint, as shown below.

curl -XGET -H "Content-Type: application/json" \
           -H "Authorization: Bearer YOUR_API_KEY" \ 
           https://sdk.split.io/api/splitChanges\?since\=-1

The response of each of the above API requests should be written to a file. For the segmentChanges/{segment_name} endpoint, the name of the file for each response should match the name of the segment requested. For the example shown above, it would be my_custom_segment.json.

Setting Up the Split SDK for Localhost Mode (Go Example)

You can follow the Split Go SDK documentation to complete the following initial steps:

1. Install the Split SDK into your Go environment
2. Import the Split SDK into your project
3. Instantiate the Split SDK

Following that, there are a few parameters that you set in your Go code to initialize your Split SDK client. This should point to your local JSON files with your split (feature flag) and segment definitions.

Provide the paths for the Split SDK to find the local JSON files.

sdkConfig.SplitFile = "./splitChange.json"
sdkConfig.SegmentDirectory = "./segments"

Use the reserved word "localhost" for the Split API key value to indicate that the data source used by Split SDK should be local files:

factory, err:= client.NewSplitFactory("localhost", sdkConfig)

With these parameters set, you are ready to read Split definitions from the JSON files. The Split SDK will even regularly poll your local files for changes and use the data to evaluate feature flags. More on this below.

Synchronizing

The Split SDK will run threads in the background to retrieve and update Split definitions. You can set this to happen at specified time intervals (in seconds), as shown below for Go:

sdkConf.TaskPeriods.SplitSync = 5 // seconds
sdkConf.TaskPeriods.SegmentSync = 5 // seconds

In localhost mode from JSON, the SDK pulls changes from the JSON files and then evaluates feature flags using the updated rules.

You can see this resyncing as it happens in real-time in the animation below. The debug information written to the terminal by the Split Go SDK indicates that Split's resync operation has been completed. You can also observe the updated feature flag return value (initially "on", updated to "off") printed to the terminal.

By resyncing on the fly, you have the flexibility to experiment and hone your user experiences in all of your scenarios, even when working offline.

Wrap Up

The world is in motion, and now you can be too, whether you want to travel across borders or just to the shady spot at the end of your backyard or garden. When your internet connection is taking a hit, your productivity does not have to.

Split is there for you with the convenience of localhost mode from JSON, already supported for Java, Go and Python.

A last nod and thank you to Nadia Mayor and Matias Melograno on the Split Team for a top-notch demo (as animated above).

Get Split Certified

Split Arcade includes product explainer videos, clickable product tutorials, manipulatable code examples, and interactive challenges.

Switch It On With Split

The Split Feature Data Platform™ gives you the confidence to move fast without breaking things. Set up feature flags and safely deploy to production, controlling who sees which features and when. Connect every flag to contextual data, so you can know if your features are making things better or worse and act without hesitation. Effortlessly conduct feature experiments like A/B tests without slowing down. Whether you’re looking to increase your releases, to decrease your MTTR, or to ignite your dev team without burning them out–Split is both a feature management platform and partnership to revolutionize the way the work gets done. Switch on a free account today, schedule a demo, or contact us for further questions.