API Lifecycle, Versioning, and Deprecation

Enterprise customers of VIER Cognitive Voice Gateway (CVG) require a release planning and stable APIs they can rely on for their production systems.

For new projects and partners the rapid delivery of new features and changes is essential to build proof of concepts and prototypes.

This document provides an overview of how we approach releases to deliver long term support as well as cutting edge technology.

For users of VIER Cognitive Voice Gateway it explains what to expect in a release and when release is done.

What’s in a Release?

The team will focus on key features for each release (resp. deployment) that will be prioritized from user feedback and actual project needs.

In some cases we might plan a certain feature to be done for a specific deployment, but in general we just work on features and merge them into the master branch when they are done.

When do we release a new Version?

We strive for APIs to be continuously developed. To manage the complexity we version our APIs. Versioning helps us to iterate faster when the needed changes are identified.

CVG APIs only are up-versioned when a breaking change is made.

Breaking changes include:

  • a new required parameter

  • a change in the format of the response data for one or more calls

  • a change in the response type (i.e. changing an integer to a float)

  • removing any part of the API

  • a materially different internal behaviour of an API call – such as a change to the default behaviour.

Breaking changes do always result in a change to the major version number for an API or content response type.

Versions with Breaking Changes

We will release versions with breaking changes not more than twice a year.

Changes of the API that are beneficial to the user and do not constitute a breaking change include:

  • adding new resources or new API endpoints

  • new optional parameters

  • changes to non-public endpoints

  • new optional keys in JSON POST body

  • new keys returned in the JSON response body

  • new entries in enumerations

Non-breaking changes do not change the major version number.

Versions with Non-Breaking Changes

We will release version with non-breaking changes frequently, e.g. every two weeks. Make sure to configure your mapping logic to accept unknown fields and enumeration entries.

How we version

We put our version directly in the URI. This makes breaking changes explicit and less complicated than other approaches, which is easier for developers.

E.g. an URI looks like https://cognitivevoice.io/v1/call/say

Separating Deployment from Release

We make use of the valuable trick of separating a deployment from a release. This way it’s possible to frequently deploy changes when they are ready through continuous delivery and deployment but we don’t always publicly announce or document them at the same time.

It’s not uncommon for us to deploy a new API endpoint or an enhancement to an existing API endpoint and use it from within the UI (CVG Console) or with internal tools before we publicly document it and support it.

That way we can make some tweaks to it for usability or conformance to standards without worrying about making a dreaded breaking change. Once we are happy with the change we add it to our public documentation.

Staging System

Bigger changes we first deploy on our staging system. That enables our partners and customers to test their software with a new CVG version before we deploy on our production system.

Deprecation Policy

When we have a newly released API version (no alpha or beta version) we deprecate the older API version.

We support a deprecated API version for a duration of 6 months after their announced deprecation. Support includes major bug fixes and major security fixes.

Exception

No policy can cover every possible situation. This policy is a living document, and will evolve over time. In practice, there will be situations that do not fit neatly into this policy, or for which this policy becomes a serious impediment. Such situations should be discussed with product managers and project leaders to find the best solutions for those specific cases, always bearing in mind that CVG is committed to being a stable system that, as much as possible, never breaks users. Exceptions will always be announced in all relevant release notes.