Versioning and Migration

Current production values

• Base URL: https://api.gamequery.dev
• Stable version: v1

Migration-ready client pattern

Do not hardcode v1 directly inside endpoint wrappers.

Use explicit configuration instead:

GQ_API_BASE_URL=https://api.gamequery.dev
GQ_API_VERSION=v1

Then build request URLs from both values.

const baseUrl = process.env.GQ_API_BASE_URL ?? 'https://api.gamequery.dev';
const version = process.env.GQ_API_VERSION ?? 'v1';

function buildUrl(path: string): string {
  return `${baseUrl}/${version}${path}`;
}

When v2 is released, moving from v1 to v2 should only require config updates and contract checks.

Recommended rollout strategy for v2

1. Test in staging with GQ_API_VERSION=v2.
2. Run request/response contract tests against your critical routes.
3. Ship a canary release in production.
4. Monitor error rates, parsing issues, and payload drift.
5. Complete production cutover once metrics stay stable.

Checklist before v2 launch

• Centralize headers and URL building in one shared client module.
• Keep endpoint-specific parsing isolated in adapter functions.
• Log non-2xx responses with route, version, and request ID.
• Track schema assumptions in tests so breaking changes are visible early.