# API Versioning {#api-versioning}


API versioning strategy, deprecation policies, and migration guidance.


## Current Version {#current-version}


The Ever Gauzy API is currently **unversioned** — all endpoints are served at `/api/`.

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


## Versioning Strategy {#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 {#nestjs-versioning-support}


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


### Per-Controller Versioning {#per-controller-versioning}


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


### Per-Endpoint Versioning {#per-endpoint-versioning}


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

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


## Deprecation Policy {#deprecation-policy}


| Phase            | Duration | Action                               |
| ---------------- | :------: | ------------------------------------ |
| **Announcement** |    —     | Release notes, docs update           |
| **Deprecated**   | 6 months | Sunset header added, warnings logged |
| **Removed**      |    —     | Endpoint returns 410 Gone            |


### Deprecation Headers {#deprecation-headers}


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


## GraphQL Versioning {#graphql-versioning}


GraphQL APIs evolve through field-level deprecation:

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


## Related Pages {#related-pages}


- [API Overview](https://sourcey-gauzy.pages.dev/api/overview/index.md)
- [REST API](https://sourcey-gauzy.pages.dev/api/rest-api/index.md)
- [Error Handling](https://sourcey-gauzy.pages.dev/api/error-handling/index.md) — error response format