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).

1
// Employee Comm Before (CSV)
2
{
3
	...,
4
	"audience": [
5
		"user1@example.com",
6
		"user2@example.com"		
7
	]
8
}
9
// Employee Comm After (CSV)
10
{
11
	...,
12
	"audience": {
13
		"type": "email_csv",
14
		"members": [
15
			"user1@example.com",
16
			"user2@example.com"		
17
		]
18
	}
19
}
20
// Employee Comm After (DL)
21
{
22
	...,
23
	"audience": {
24
		"type": "distribution_list",
25
		"target": {
26
			"source": "active_directory",
27
			"dl_name": "customer-success@moveworks.ai"
28
		}
29
	}
30
}

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.

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.