---
title: API Release Management
excerpt: ''
deprecated: false
hidden: false
metadata:
  title: ''
  description: ''
  robots: index
next:
  description: ''
---
# 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).

```jsx
// Employee Comm Before (CSV)
{
	...,
	"audience": [
		"user1@example.com",
		"user2@example.com"		
	]
}
// Employee Comm After (CSV)
{
	...,
	"audience": {
		"type": "email_csv",
		"members": [
			"user1@example.com",
			"user2@example.com"		
		]
	}
}
// Employee Comm After (DL)
{
	...,
	"audience": {
		"type": "distribution_list",
		"target": {
			"source": "active_directory",
			"dl_name": "customer-success@moveworks.ai"
		}
	}
}
```

**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](https://developer.moveworks.com/creator-studio/integrations/inbound/experimental-apis/)).
  * **Base Versions (`/v1`)** - These are stable releases.
* When can customers get access to the product?
  * At the`beta` 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.

<Table>
  <thead>
    <tr>
      <th>
        Roadmap Item
      </th>

      <th>
        Example Step
      </th>

      <th>
        Traditional Lifecycle Stage
      </th>

      <th>
        API Version Number
      </th>

      <th>
        Explanation
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        V1
      </td>

      <td>
        Build a version for internal testing\
        (e.g. message API with single recipient) 
      </td>

      <td>
         Employee Rollout
      </td>

      <td>
        /v1alpha1
      </td>

      <td>
        v1 = new base version\
        alpha1 = the first alpha
      </td>
    </tr>

    <tr>
      <td>
        V1
      </td>

      <td>
        Share the version for feedback with a few design customers, informing them not to use with production systems 
      </td>

      <td>
         Limited Preview
      </td>

      <td>
        /v1alpha1
      </td>

      <td>
        No changes needed since same interface for external non-production consumption
      </td>
    </tr>

    <tr>
      <td>
        V1 
      </td>

      <td>
        Iterate on feedback for a second internal version  

        (e.g. message API with multiple recipients)
      </td>

      <td>
        Limited Preview
      </td>

      <td>
        /v1alpha2
      </td>

      <td>
        alpha2 = the second alpha for v1
      </td>
    </tr>

    <tr>
      <td>
        V1
      </td>

      <td>
        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.
      </td>

      <td>
        Limited Preview 
      </td>

      <td>
        /v1beta1
      </td>

      <td>
        beta1 = the first beta version for v1
      </td>
    </tr>

    <tr>
      <td>
        V1 
      </td>

      <td>
        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.
      </td>

      <td>
        Preview
      </td>

      <td>
        /v1beta2
      </td>

      <td>
        beta2 = the second version for v1
      </td>
    </tr>

    <tr>
      <td>
        V1
      </td>

      <td>
        Feedback is collected and no changes are needed. Release GA-ready version
      </td>

      <td>
        GA
      </td>

      <td>
        /v1
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        \{Feature} for V1
      </td>

      <td>
        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)
      </td>

      <td>
        Employee Rollout
      </td>

      <td>
        /v1alpha3
      </td>

      <td>
        v1 - non-breaking change\
        alpha3 - the next alpha number
      </td>
    </tr>

    <tr>
      <td>
        \{Feature} for V1
      </td>

      <td>
        Release non-breaking change to LP
      </td>

      <td>
        Limited Preview
      </td>

      <td>
         /v1beta3
      </td>

      <td>
        beta3 - the next beta number
      </td>
    </tr>

    <tr>
      <td>
        \{Feature} for V1
      </td>

      <td>
        Release non-breaking change to GA
      </td>

      <td>
        GA
      </td>

      <td>
        /v1
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        V2
      </td>

      <td>
        Start on a new feature that is a breaking change  

        (e.g. send an email alongside the AI Assistant notification)
      </td>

      <td>
        Employee Rollout
      </td>

      <td>
        /v2alpha1
      </td>

      <td>
        v2 = new base version since breaking\
        v2alpha1 = first alpha for v2
      </td>
    </tr>

    <tr>
      <td>
        V2
      </td>

      <td>
        Release breaking change to LP
      </td>

      <td>
        Limited Preview
      </td>

      <td>
        /v2beta1
      </td>

      <td>
        v2beta1 = first beta for v2
      </td>
    </tr>

    <tr>
      <td>
        V2
      </td>

      <td>
        Release /v2
      </td>

      <td>
        GA
      </td>

      <td>
        /v2
      </td>

      <td>

      </td>
    </tr>
  </tbody>
</Table>

<br />

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