API Release Management

Overview

API Release Management is the rollout & distribution of API products from Moveworks. It governs how APIs are made available to customers, how they are versioned, and how they are deprecated.

Why are APIs released differently from our core product?

With our UI-based products, we are designing interfaces for humans to interact with. As a result, we’re allowed to change the way that someone does something in the product, without breaking functionality.

For example, when we added the ability to send Employee Comms to distribution lists, we were able to change the “Select Audience” page to let the user choose between CSV mode and Audience Builder mode.

However, with API products, the interface is much more brittle. Since customers are writing code to integrate with our APIs, they can’t react to interface changes. Imagine we exposed Employee Comms over an API instead of a UI. We would need to introduce a breaking change (since the previous data model is now invalid).

// Employee Comm Before (CSV)
{
	...,
	"audience": [
		"[email protected]",
		"[email protected]"		
	]
}
// Employee Comm After (CSV)
{
	...,
	"audience": {
		"type": "email_csv",
		"members": [
			"[email protected]",
			"[email protected]"		
		]
	}
}
// Employee Comm After (DL)
{
	...,
	"audience": {
		"type": "distribution_list",
		"target": {
			"source": "active_directory",
			"dl_name": "[email protected]"
		}
	}
}

During the early days of new APIs, there will likely be many breaking changes. That means that our early adopters developers at the ready to update their code and minimize any outages built with our new APIs.

How are our APIs released?

Overview

There are 3 main stages:
- Alpha Versions (/v1alpha1) - These are unstable releases for a new base version. Primarily designed for internal & non-production consumption only.
- Beta Versions (/v1beta1) - These are semi-stable releases for a new base version. They are meant for external & production usage, but can be used internally as well. Beta APIs are subject to short-term deprecation (example Message API Beta Endpoint).
- Base Versions (/v1) - These are stable releases.
When can customers get access to the product?
- At thebeta stage, in alpha Moveworks employees will only have access to it.
Why did we use these words instead of employee rollout, limited preview, and preview?
- We decided to use a different naming convention for API Release lifecycle steps, to align with the industry standard

Example

Here is an example evolution of an API through the API release lifecycle.

Roadmap Item	Example Step	Traditional Lifecycle Stage	API Version Number	Explanation
V1	Build a version for internal testing (e.g. message API with single recipient)	Employee Rollout	/v1alpha1	v1 = new base version alpha1 = the first alpha
V1	Share the version for feedback with a few design customers, informing them not to use with production systems	Limited Preview	/v1alpha1	No changes needed since same interface for external non-production consumption
V1	Iterate on feedback for a second internal version (e.g. message API with multiple recipients)	Limited Preview	/v1alpha2	alpha2 = the second alpha for v1
V1	Release a version to a limited set of customers for initial feedback. We feel confident about the schema of the API, so it’s okay for customers to use it in production.	Limited Preview	/v1beta1	beta1 = the first beta version for v1
V1	Iterate on customer feedback for another round of feedback & release to more customers. We haven’t completed all load testing or may have degraded rate limits.	Preview	/v1beta2	beta2 = the second version for v1
V1	Feedback is collected and no changes are needed. Release GA-ready version	GA	/v1
{Feature} for V1	Work on a new non-breaking API change (e.g. we add a feature to add Message API logs to Unified log viewer, but want to add an optional parameter that suppressing logging)	Employee Rollout	/v1alpha3	v1 - non-breaking change alpha3 - the next alpha number
{Feature} for V1	Release non-breaking change to LP	Limited Preview	/v1beta3	beta3 - the next beta number
{Feature} for V1	Release non-breaking change to GA	GA	/v1
V2	Start on a new feature that is a breaking change (e.g. send an email alongside the AI Assistant notification)	Employee Rollout	/v2alpha1	v2 = new base version since breaking v2alpha1 = first alpha for v2
V2	Release breaking change to LP	Limited Preview	/v2beta1	v2beta1 = first beta for v2
V2	Release /v2	GA	/v2

How does the Beta stage work?

Beta API Behaviors

What are the performance implications of beta ?
- the last version of beta will be the base version, as we want to minimize migration overhead and have a tested version of base
How long is beta stage?
- Our goal is to migrate from beta to base version as quickly as possible. This should generally happen within 6 months.
What is the timeline for deprecation of beta ?
- Once a stable base version is released, we notify customers at least 6 months in advance to migrate OFF the beta API before it is deprecated.

Updated 1 day ago