ื“ืœื’ ืœืชื•ื›ืŸ ื”ืจืืฉื™

API Versioning

API versioning strategy, deprecation policies, and migration guidance.

Current Versionโ€‹

The Ever Gauzy API is currently unversioned โ€” all endpoints are served at /api/.

https://api.yourdomain.com/api/employee

Versioning Strategyโ€‹

When breaking changes are introduced, the API will adopt URI-based versioning:

https://api.yourdomain.com/api/v1/employee
https://api.yourdomain.com/api/v2/employee

NestJS Versioning Supportโ€‹

app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: "1",
});

Per-Controller Versioningโ€‹

@Controller({ path: "employee", version: "2" })
export class EmployeeV2Controller {
  // v2 endpoints
}

Per-Endpoint Versioningโ€‹

@Get()
@Version('1')
findAllV1() { ... }

@Get()
@Version('2')
findAllV2() { ... }

Deprecation Policyโ€‹

PhaseDurationAction
Announcementโ€”Release notes, docs update
Deprecated6 monthsSunset header added, warnings logged
Removedโ€”Endpoint returns 410 Gone

Deprecation Headersโ€‹

Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Deprecation: true
Link: <https://docs.gauzy.co/migration>; rel="successor-version"

GraphQL Versioningโ€‹

GraphQL APIs evolve through field-level deprecation:

type Employee {
  name: String @deprecated(reason: "Use firstName and lastName")
  firstName: String
  lastName: String
}