Since we first released our public API, we've supported the JSON Patch standard as the primary message format to modify specific parts of a resource in LaunchDarkly without having to replace the entire thing. This is what's allowed us and other clients that use our API to do things like toggle a flag with a simple patch like this:
JSON Patch is very flexible and works with any resource in our API,but going beyond simple cases like toggling a flag can quickly turn cumbersome. The following JSON Patch is an example of how to specify removing a few individual user targets from a flag:
This clearly illustrates several issues with JSON Patch:
- First, it’s not immediately clear what this patch is doing unless you know the JSON representation of a flag. This makes it difficult to construct these patches by hand, and difficult to debug if something unexpected happens.
- The other issue is that it requires the client to know the existing state of a resource to be able to create an appropriate patch. In this case, it needs to know the index of the user target in the JSON array in the flag’s JSON representation. This further complicates things and can require making an extra API request to get the current state before actually making a change.
To improve this situation, we brainstormed and built an alternative form of patch that we’re calling Semantic Patch. A semantic patch allows you to describe the change you want to make in terms of higher-level changes that you’d like to make to the flag rather than a detailed JSON diff. This allows the patch to capture the actual intent of the change rather than being specifically tied to the current flag state and representation.
Using this new semantic patch, the request to toggle a flag would look like this:
And the request to remove user targets looks like this:
Even if your team isn’t using our API, this change has unlocked some new and exciting features that we’re working on. Since we have a comprehensible list of changes you’re going to make to a flag, you can now review the list of changes before you actually make them.
While having this makes it easier for us to deliver on the product vision for Feature Workflows, a specific example of a feature that’s powered by semantic patches is Scheduled Flag Changes—which will allow making a change to a flag’s configuration and setting it to happen at a later date/time. This is a perfect use case for semantic patch, as the state of the flag may change before the scheduled change actually fires, so we needed a way to make sure the scheduled change still happens as intended.
Semantic patches will also be able to specify relative changes to the flag’s state, such as increasing the rollout percentage of a flag rather than setting it to a specific number. This distinction doesn’t matter when you directly change a flag, but it allows scheduling changes for the future that depend on the flag’s state without the client needing to know what the state will be.
We’ve already been using semantic patch for the API endpoints for expiring user targets, where you can use them to set user targets to expire and manage existing expirations. Now, we’re adding the ability to patch flag configurations as well. The existing flag PATCH endpoint remains unchanged, and will continue to accept JSON Patches going forward. However, if you send a special header (Content-Type: domain-model=launchdarkly.semanticpatch) along with a flag PATCH request, the request will be interpreted as a semantic patch.
If you’d like to try this out, you can use any of the examples from this post or check out the API documentation for more details on the supported instructions. Also, if you’re using JSON Patch, don’t worry—it will continue to be supported. Currently, anything that can be changed through the flag targeting page is supported through semantic patch, and we plan to support more changes soon.
Lastly, if you have feedback, please email feedback@launchdarkly.com. Thanks for reading!
