Versioning Express APIs

Welcome back! In the previous lesson, you added bounded pagination and standardized successful JSON responses around the { data, meta } contract. The API now exposes predictable collection metadata, stable sorting, request IDs, and duration information. In this lesson, you’ll introduce API versioning without copying the ticket feature. The canonical API will live under /api/v1, while the existing /api/tickets path remains temporarily available as a deprecated compatibility surface. Both paths will reuse the same routers, repositories, validation, authentication, authorization, workflows, and response formatting.

Why APIs Need Versions

An API contract includes more than its endpoint paths. Clients may depend on: Request fields and validation rules. Response structures such as { data, meta } . Authentication requirements. Status codes and error codes. Pagination behavior. Workflow transitions. Resource names and URL layouts. Changing these contracts in place can break existing consumers. Versioned namespaces give the server a stable place to introduce future changes while preserving older behavior during a migration period. The canonical namespace in this project is: text /api/v1 Its ticket resource is available at: text /api/v1/tickets The earlier path remains temporarily available: text /api/tickets The old path is not a separate implementation. It is a compatibility mount that points to the same ticket router and adds migration headers.

Understanding the Versioned Route Structure

The final route composition looks like this: text Express application │ ├── /health │ ├── /api/v1 │ ├── GET / │ └── /tickets │ └── shared ticketRoutes │ └── /api └── /tickets └── shared ticketRoutes The resulting public endpoints include: text GET /api/v1 GET /api/v1/tickets POST /api/v1/tickets GET /api/v1/tickets/:ticketId and their temporary legacy equivalents: text GET /api/tickets POST /api/tickets GET /api/tickets/:ticketId Only the composition and response headers differ. Ticket behavior remains owned by one shared feature router.

Composition Routers Instead of Duplicated Features

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Versioning is implemented through small composition routers:

text

apiV1Routes
    └── mounts ticketRoutes

legacyApiRoutes
    └── mounts the same ticketRoutes

apiV1Routes
    └── mounts ticketRoutes

legacyApiRoutes
    └── mounts the same ticketRoutes

Neither composition router reimplements:

Ticket collection handlers.
Ticket creation.
Detail retrieval.
Updates or deletion.
Nested comments.
Workflow actions.
Authentication.
Authorization.
Zod validation.
PostgreSQL repositories.
Success-envelope formatting.

This keeps the application’s behavior consistent across both paths and avoids maintaining two copies of the same API.

The canonical composition router lives in src/routes/api-v1-routes.ts.

TypeScript

import { Router } from "express";

import { sendSuccess } from "../lib/response.js";
import { ticketRoutes } from "./ticket-routes.js";

export const apiV1Routes = Router();

import { Router } from "express";

import { sendSuccess } from "../lib/response.js";
import { ticketRoutes } from "./ticket-routes.js";

export const apiV1Routes = Router();

apiV1Routes is a normal Express router. Its purpose is to organize version-level behavior rather than implement ticket functionality.
sendSuccess() allows the discovery endpoint to use the same stabilized response envelope as other successful API responses.
ticketRoutes is imported and mounted directly. The version router does not copy its handlers or create another ticket feature.

The version router applies middleware before its discovery route and nested ticket mount.

TypeScript

apiV1Routes.use((_request, response, next) => {
  response.setHeader("X-API-Version", "1");
  next();
});

apiV1Routes.use((_request, response, next) => {
  response.setHeader("X-API-Version", "1");
  next();
});

Router-level middleware runs for every request that enters /api/v1.
X-API-Version: 1 is set before the discovery endpoint or ticket router handles the request.
Calling next() allows routing to continue while preserving the response header.
The header appears on successful discovery responses, ticket resources, validation failures, authorization failures, and other responses that pass through this router before reaching the final error handler.

This gives clients an explicit indication of the API version that handled the request.

The canonical router provides a public discovery endpoint at GET /api/v1.

TypeScript

apiV1Routes.get("/", (_request, response) => {
  sendSuccess(response, {
    version: "1",
    resources: ["tickets"],
  });
});

apiV1Routes.get("/", (_request, response) => {
  sendSuccess(response, {
    version: "1",
    resources: ["tickets"],
  });
});

The local path is "/", but the application mounts the router at /api/v1. The complete endpoint is therefore GET /api/v1.
The route does not use authenticate, so clients can discover the current API version without a Bearer token.
version identifies the canonical contract.
resources advertises the top-level resources currently available under the versioned namespace.
sendSuccess() wraps the discovery object in { data, meta } and includes request context when available.

A successful response resembles:

JSON

{
  "data": {
    "version": "1",
    "resources": [
      "tickets"
    ]
  },
  "meta": {
    "requestId": "3f251a65-e063-4af0-b2d1-f194d576f702",
    "durationMs": 1
  }
}

{
  "data": {
    "version": "1",
    "resources": [
      "tickets"
    ]
  },
  "meta": {
    "requestId": "3f251a65-e063-4af0-b2d1-f194d576f702",
    "durationMs": 1
  }
}

The response headers also include:

text

X-API-Version: 1

X-API-Version: 1

The discovery endpoint belongs to apiV1Routes, while authentication remains inside ticketRoutes.

TypeScript

apiV1Routes.use("/tickets", ticketRoutes);

apiV1Routes.use("/tickets", ticketRoutes);

The shared ticket router is mounted at the local path /tickets.
Because apiV1Routes is mounted at /api/v1, the complete ticket path becomes /api/v1/tickets.
ticketRoutes still calls ticketRoutes.use(authenticate), so its resources require a valid Bearer token.
Authentication is not moved to the version router because that would also protect GET /api/v1.

This preserves a useful separation:

text

GET /api/v1
    → public discovery

/api/v1/tickets/*
    → authentication and authorization owned by ticketRoutes

GET /api/v1
    → public discovery

/api/v1/tickets/*
    → authentication and authorization owned by ticketRoutes

The compatibility router lives in src/routes/legacy-api-routes.ts.

TypeScript

import { Router } from "express";

import { ticketRoutes } from "./ticket-routes.js";

export const legacyApiRoutes = Router();

import { Router } from "express";

import { ticketRoutes } from "./ticket-routes.js";

export const legacyApiRoutes = Router();

Like the canonical router, it imports the existing ticket router rather than creating another implementation.

Its responsibility is to expose the old path and attach migration information.

The legacy router applies three headers before passing the request to the shared ticket feature.

TypeScript

legacyApiRoutes.use((_request, response, next) => {
  response.setHeader("Deprecation", "true");
  response.setHeader(
    "Sunset",
    "Thu, 31 Dec 2026 23:59:59 GMT",
  );
  response.setHeader(
    "Link",
    '</api/v1>; rel="successor-version"',
  );

  next();
});

legacyApiRoutes.use((_request, response, next) => {
  response.setHeader("Deprecation", "true");
  response.setHeader(
    "Sunset",
    "Thu, 31 Dec 2026 23:59:59 GMT",
  );
  response.setHeader(
    "Link",
    '</api/v1>; rel="successor-version"',
  );

  next();
});

Deprecation: true tells clients that the requested API surface is still available but should no longer be preferred.
Sunset provides a fixed HTTP date indicating when the compatibility surface is expected to be retired.
Link points clients toward /api/v1 and labels it as the successor version.
Calling next() preserves all three headers while the shared ticket router handles the actual request.

These headers communicate migration information without changing the successful { data, meta } body.

The compatibility router mounts the same ticket feature:

TypeScript

legacyApiRoutes.use("/tickets", ticketRoutes);

legacyApiRoutes.use("/tickets", ticketRoutes);

When legacyApiRoutes is mounted at /api, the complete resource path becomes:

text

/api/tickets

/api/tickets

The legacy route still supports the complete ticket surface:

text

GET    /api/tickets
POST   /api/tickets
GET    /api/tickets/:ticketId
PATCH  /api/tickets/:ticketId
DELETE /api/tickets/:ticketId

POST /api/tickets/:ticketId/assign
POST /api/tickets/:ticketId/close
POST /api/tickets/:ticketId/reopen

GET  /api/tickets/:ticketId/comments
POST /api/tickets/:ticketId/comments

GET    /api/tickets
POST   /api/tickets
GET    /api/tickets/:ticketId
PATCH  /api/tickets/:ticketId
DELETE /api/tickets/:ticketId

POST /api/tickets/:ticketId/assign
POST /api/tickets/:ticketId/close
POST /api/tickets/:ticketId/reopen

GET  /api/tickets/:ticketId/comments
POST /api/tickets/:ticketId/comments

The handlers, status codes, authorization rules, and response envelopes are identical to the canonical surface.

These requests reach the same collection handler:

text

GET /api/v1/tickets?pageSize=2
GET /api/tickets?pageSize=2

GET /api/v1/tickets?pageSize=2
GET /api/tickets?pageSize=2

Given the same authenticated user and database state, their JSON responses should contain the same ticket data and pagination metadata.

The canonical response includes:

text

X-API-Version: 1

X-API-Version: 1

The legacy response includes:

text

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

The response body is not converted into a separate legacy format. Both surfaces use:

JSON

{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 2,
    "total": 12,
    "totalPages": 6
  }
}

{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 2,
    "total": 12,
    "totalPages": 6
  }
}

This allows clients to migrate paths without also adapting to another payload contract.

Mounting Version Routers in the Application

The final application composition is defined in src/app.ts.

TypeScript

import cors from "cors";
import express from "express";
import morgan from "morgan";

import { env } from "./config/env.js";
import { errorHandler } from "./middleware/error-handler.js";
import { notFound } from "./middleware/not-found.js";
import { requestContext } from "./middleware/request-context.js";
import { apiV1Routes } from "./routes/api-v1-routes.js";
import { healthRoutes } from "./routes/health-routes.js";
import { legacyApiRoutes } from "./routes/legacy-api-routes.js";

import cors from "cors";
import express from "express";
import morgan from "morgan";

import { env } from "./config/env.js";
import { errorHandler } from "./middleware/error-handler.js";
import { notFound } from "./middleware/not-found.js";
import { requestContext } from "./middleware/request-context.js";
import { apiV1Routes } from "./routes/api-v1-routes.js";
import { healthRoutes } from "./routes/health-routes.js";
import { legacyApiRoutes } from "./routes/legacy-api-routes.js";

The application imports the two composition routers instead of importing ticketRoutes directly.
Ticket behavior remains indirectly available through both routers.

The mounts are placed after global middleware and operational routes.

TypeScript

export function createApp() {
  const app = express();

  app.use(requestContext);
  app.use(cors());
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  if (env.NODE_ENV !== "test") {
    app.use(morgan("dev"));
  }

  app.use(healthRoutes);
  app.use("/api/v1", apiV1Routes);
  app.use("/api", legacyApiRoutes);

  app.use(notFound);
  app.use(errorHandler);

  return app;
}

export function createApp() {
  const app = express();

  app.use(requestContext);
  app.use(cors());
  app.use(express.json());
  app.use(express.urlencoded({ extended: true }));

  if (env.NODE_ENV !== "test") {
    app.use(morgan("dev"));
  }

  app.use(healthRoutes);
  app.use("/api/v1", apiV1Routes);
  app.use("/api", legacyApiRoutes);

  app.use(notFound);
  app.use(errorHandler);

  return app;
}

Request context still runs first, providing request IDs and timing information.
Body parsers still run before routes that validate JSON bodies.
The health route remains outside the versioned API namespace because it is an operational endpoint.
The canonical /api/v1 router is mounted before the broader /api compatibility router.
Both API mounts appear before notFound.
The four-argument error handler remains last.

The old direct mount is removed:

TypeScript

// Removed:
app.use("/api/tickets", ticketRoutes);

// Removed:
app.use("/api/tickets", ticketRoutes);

The legacy router now provides that path through composition instead.

Express combines application mount paths with router-local paths.

For the canonical surface:

text

Application mount: /api/v1
Version router:    /tickets
Ticket router:     /
--------------------------------
Final path:        /api/v1/tickets

Application mount: /api/v1
Version router:    /tickets
Ticket router:     /
--------------------------------
Final path:        /api/v1/tickets

For the legacy surface:

text

Application mount: /api
Legacy router:     /tickets
Ticket router:     /
--------------------------------
Final path:        /api/tickets

Application mount: /api
Legacy router:     /tickets
Ticket router:     /
--------------------------------
Final path:        /api/tickets

Nested ticket routes continue composing beneath those bases:

text

/api/v1/tickets/:ticketId/comments
/api/tickets/:ticketId/comments

/api/v1/tickets/:ticketId/comments
/api/tickets/:ticketId/comments

No feature handler needs to know which composition router was used.

Both composition modules import the same exported router:

TypeScript

import { ticketRoutes } from "./ticket-routes.js";

import { ticketRoutes } from "./ticket-routes.js";

This means both public surfaces share:

Router-wide authentication.
Customer collection scoping.
Agent and administrator role checks.
Ticket ownership checks.
Zod schemas.
Media-type requirements.
PostgreSQL queries.
Workflow services.
Nested comments.
Method-not-allowed handling.
Success-envelope formatting.

A future bug fix in the ticket router automatically affects both mounts. There is no separate legacy implementation to update.

Ticket creation uses request.baseUrl when constructing its Location response header.

TypeScript

.post(
  requireJson,
  validateRequest({
    body: createTicketBodySchema,
  }),
  async (request, response) => {
    const user = getCurrentUser(response);

    const { body } =
      response.locals.validated as {
        body: CreateTicketBody;
      };

    const ticket = await createTicket({
      ...body,
      requesterId: user.id,
    });

    response.setHeader(
      "Location",
      `${request.baseUrl}/${ticket.id}`,
    );

    sendSuccess(response, ticket, 201);
  },
)

request.baseUrl contains the path through which the current router was reached.
A canonical creation request uses /api/v1/tickets as its base URL.
The generated resource ID is appended to that mount.

A request to:

text

POST /api/v1/tickets

therefore returns a header resembling:

text

Location: /api/v1/tickets/tkt_9a57a9f8-92f0-4a31-8491-222bf03704c9

This is safer than hard-coding /api/tickets, which would produce an outdated path after versioning.

Because request.baseUrl reflects the actual mount, creating through the legacy route would produce a legacy location:

text

POST /api/tickets

POST /api/tickets

text

Location: /api/tickets/tkt_<generated-id>

Location: /api/tickets/tkt_<generated-id>

Creating through the canonical route produces the preferred canonical location:

text

POST /api/v1/tickets

POST /api/v1/tickets

text

Location: /api/v1/tickets/tkt_<generated-id>

Location: /api/v1/tickets/tkt_<generated-id>

Clients should use the canonical surface for new integrations. The compatibility route exists to support migration, not to replace version 1 as the preferred namespace.

Repositories do not know whether a request arrived through /api/v1/tickets or /api/tickets.

For example, listTickets() still receives the same typed options:

TypeScript

const result = await listTickets({
  ...query,
  ...(user.role === "customer"
    ? { requesterId: user.id }
    : {}),
});

const result = await listTickets({
  ...query,
  ...(user.role === "customer"
    ? { requesterId: user.id }
    : {}),
});

Its PostgreSQL query still:

Parameterizes filters.
Uses fixed sort expressions.
Applies stable ordering.
Parameterizes LIMIT and OFFSET.
Returns the filtered count.

Versioning changes route composition and metadata. It does not change persistence behavior.

The shared ticket router still mounts authentication once:

TypeScript

export const ticketRoutes = Router();

ticketRoutes.use(authenticate);

export const ticketRoutes = Router();

ticketRoutes.use(authenticate);

Both paths therefore have the same security requirements:

text

GET /api/v1/tickets
GET /api/tickets

GET /api/v1/tickets
GET /api/tickets

Both require a Bearer token.

A customer sees only their own collection through either path. Agents and administrators can access the broader collection according to the same rules.

Workflow actions remain agent- or admin-only under both namespaces:

text

POST /api/v1/tickets/:ticketId/close
POST /api/tickets/:ticketId/close

POST /api/v1/tickets/:ticketId/close
POST /api/tickets/:ticketId/close

Versioning does not create a security bypass because both mounts reuse the same router.

The version root is public:

text

GET /api/v1

GET /api/v1

The ticket collection remains authenticated:

text

GET /api/v1/tickets

GET /api/v1/tickets

This design allows a client to learn which API version and resources exist before supplying credentials.

The legacy router does not define a matching discovery endpoint at /api. Its purpose is only to preserve the old ticket path while directing clients toward the canonical version.

Only version 1 is registered:

TypeScript

app.use("/api/v1", apiV1Routes);

app.use("/api/v1", apiV1Routes);

A request such as:

text

GET /api/v2

GET /api/v2

does not match a version router. It continues to the shared notFound middleware and returns the established error contract:

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Route GET /api/v2 was not found."
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 1
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Route GET /api/v2 was not found."
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 1
  }
}

The application does not silently redirect unsupported versions or treat them as version 1.

Keep the base URL set to:

text

http://localhost:4000

http://localhost:4000

Send the public request:

text

GET /api/v1

GET /api/v1

No Bearer token is required.

Inspect the response body and confirm:

JSON

{
  "data": {
    "version": "1",
    "resources": [
      "tickets"
    ]
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 1
  }
}

{
  "data": {
    "version": "1",
    "resources": [
      "tickets"
    ]
  },
  "meta": {
    "requestId": "generated-request-id",
    "durationMs": 1
  }
}

Then inspect the response headers and confirm:

text

X-API-Version: 1

X-API-Version: 1

Open the Authorization tab, choose Bearer Token, and enter:

text

agent-token-1

agent-token-1

Send the canonical request:

text

GET /api/v1/tickets?pageSize=2

GET /api/v1/tickets?pageSize=2

Then send the compatibility request:

text

GET /api/tickets?pageSize=2

GET /api/tickets?pageSize=2

Both responses should contain equivalent ticket arrays under data and matching pagination fields under meta, assuming the database did not change between requests.

The canonical response should include:

text

X-API-Version: 1

X-API-Version: 1

The legacy response should include:

text

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

Only the compatibility route advertises deprecation.

With agent-token-1, send:

text

POST /api/v1/tickets

POST /api/v1/tickets

Use a JSON body such as:

JSON

{
  "title": "Versioned route creation check",
  "description": "Created through the canonical API namespace.",
  "priority": "medium"
}

{
  "title": "Versioned route creation check",
  "description": "Created through the canonical API namespace.",
  "priority": "medium"
}

The request should return 201 Created with the ticket under data.

Inspect the Location response header:

text

Location: /api/v1/tickets/<new-id>

Location: /api/v1/tickets/<new-id>

The path should begin with /api/v1/tickets/, proving that ticket creation adapts to its mount rather than relying on a hard-coded legacy path.

Copy the new ticket ID and request it through the compatibility path:

text

GET /api/tickets/<new-id>

GET /api/tickets/<new-id>

The ticket should be returned because both mounts use the same repository and PostgreSQL data.

The response should also include the legacy migration headers. This demonstrates that versioning affects routing and response metadata, not database separation.

Request the ticket through its canonical location:

text

GET /api/v1/tickets/<new-id>

GET /api/v1/tickets/<new-id>

The data object should match the legacy response’s ticket representation.

The canonical response includes X-API-Version: 1, while the legacy response includes migration headers.

Version and migration middleware run before the ticket feature. Their headers therefore remain available even when a nested route produces an error.

For example:

text

GET /api/v1/tickets/tkt_missing

GET /api/v1/tickets/tkt_missing

should return TICKET_NOT_FOUND and include:

text

X-API-Version: 1

X-API-Version: 1

The equivalent legacy request:

text

GET /api/tickets/tkt_missing

GET /api/tickets/tkt_missing

should return the same error body while including:

text

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

Deprecation: true
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: </api/v1>; rel="successor-version"

The centralized error handler remains shared across both surfaces.

The -i option includes response headers, which makes it useful for verifying version metadata.

Shell

curl -i "http://localhost:4000/api/v1/tickets?pageSize=2" -H "Authorization: Bearer agent-token-1"

curl -i "http://localhost:4000/api/v1/tickets?pageSize=2" -H "Authorization: Bearer agent-token-1"

Look for:

text

HTTP/1.1 200 OK
X-API-Version: 1

HTTP/1.1 200 OK
X-API-Version: 1

The JSON body should use the same { data, meta } envelope shown in the API Simulator.

For the compatibility route, change the path to:

text

http://localhost:4000/api/tickets?pageSize=2

http://localhost:4000/api/tickets?pageSize=2

and inspect the deprecation headers.

Versioned routing does not replace the established Express pipeline.

The final order remains:

text

requestContext
    ↓
CORS
    ↓
JSON and URL-encoded parsers
    ↓
request logging
    ↓
health routes
    ↓
canonical API router
    ↓
legacy compatibility router
    ↓
notFound
    ↓
errorHandler

requestContext
    ↓
CORS
    ↓
JSON and URL-encoded parsers
    ↓
request logging
    ↓
health routes
    ↓
canonical API router
    ↓
legacy compatibility router
    ↓
notFound
    ↓
errorHandler

This order matters:

Request IDs exist before version or feature routes run.
JSON is parsed before validation middleware reads request bodies.
Version and deprecation headers are set before ticket responses are generated.
Unmatched paths reach notFound.
Thrown or delegated errors reach the final four-argument handler.

Do not copy the ticket router into a separate ticket-v1-routes.ts merely to change the URL prefix. That would duplicate behavior without creating a genuinely different contract.

Do not duplicate repository functions for version 1. PostgreSQL access is independent of the route namespace.

Do not mount authentication across all of /api/v1, because the discovery endpoint is intentionally public.

Do not hard-code creation locations. request.baseUrl keeps the resource path aligned with the current mount.

Do not remove the legacy route without migration metadata. The purpose of the compatibility surface is to keep old clients working while clearly advertising the successor.

The canonical API now includes:

text

GET /api/v1
GET /api/v1/tickets
POST /api/v1/tickets
GET /api/v1/tickets/stats
GET /api/v1/tickets/:ticketId
PATCH /api/v1/tickets/:ticketId
DELETE /api/v1/tickets/:ticketId
POST /api/v1/tickets/:ticketId/assign
POST /api/v1/tickets/:ticketId/close
POST /api/v1/tickets/:ticketId/reopen
GET /api/v1/tickets/:ticketId/comments
POST /api/v1/tickets/:ticketId/comments

GET /api/v1
GET /api/v1/tickets
POST /api/v1/tickets
GET /api/v1/tickets/stats
GET /api/v1/tickets/:ticketId
PATCH /api/v1/tickets/:ticketId
DELETE /api/v1/tickets/:ticketId
POST /api/v1/tickets/:ticketId/assign
POST /api/v1/tickets/:ticketId/close
POST /api/v1/tickets/:ticketId/reopen
GET /api/v1/tickets/:ticketId/comments
POST /api/v1/tickets/:ticketId/comments

The compatibility API temporarily preserves the same ticket operations beneath:

text

/api/tickets

/api/tickets

Clients should migrate toward /api/v1, using the legacy response headers as guidance.

You’ve introduced a canonical versioned namespace without duplicating the ticket feature.

apiV1Routes sets X-API-Version: 1, provides public discovery at GET /api/v1, and mounts the existing ticket router at /tickets. legacyApiRoutes mounts the same ticket router while adding Deprecation, Sunset, and successor-version Link headers.

The application now mounts the canonical router at /api/v1 and the compatibility router at /api. Authentication, authorization, validation, repositories, workflows, pagination, and response envelopes remain owned by shared code.

Finally, request.baseUrl allows ticket creation to generate a Location header that matches the route used for the request. The API can now evolve through explicit namespaces while preserving a controlled migration path for existing clients.