Versioning and Migration

Raw markdown source view for LLM workflows.

---
title: Versioning and Migration
description: Prepare your integration now so migrating from v1 to v2 is mostly configuration.
---

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

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

Then build request URLs from both values.

```ts
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.