Multi-version life-cycle for API (using for example Trunk-Based Development)

lifecycle-api-multiple-versions.md

Multi-version life-cycle for API (using for example Trunk-Based Development)

Rather than deploy separate versioned backends—which may be either misguided, expensive, hard to manage, keep track of, update and so on—consider using a continuously updated, "living" approach to keeping systems functional for your applications/systems, even those that you will soon no longer support.

The below gives the scenario handled in the accompanying Javascript code.

Scenario

Client A (v 1.0, public production version) calls backend with:

GET www.domain.com/api

Expects:

{
  "response": "This is the current production response"
}

Client B (v 1.1, limited beta version) calls the same backend with:

GET www.domain.com/api

Expects:

{
  "data": {
    "text": "This is the new beta response"
  }
}

tbd-multi-version-demo.js

/**
 * @description API that caters for current (production) requirements, as well as future (beta) data needs.
 * Uses a kind of primitive feature toggle to switch version, without needing to deploy and maintain two separate backends.
 */
function api(event) {
  const clientVersion = event?.headers["X-Client-Version"];

  // Return data structure expected of current version
  if (!clientVersion || parseFloat(clientVersion) < 1.1) return dataCurrent();

  // Return new data structure
  return dataBeta();
}

/**
 * @description This is the current production response.
 *
 * @version 1.0.0
 * @deprecated Will be deprecated after version 1.1
 */
const dataCurrent = () => ({
  "response": "This is the current production response"
});

/**
 * @description This is the new beta response.
 *
 * @version 1.1.0
 */
const dataBeta = () => ({
  "data": {
    "text": "This is the new beta response"
  }
});

/**
 * @description Call API with both current and future application versions.
 */
const responseProd = api();
console.log('Production response:', responseProd);

const responseBeta = api({ headers: { "X-Client-Version": "1.1" } });
console.log('Beta response:', responseBeta);