---
title: API Versioning Strategy
impact: MEDIUM
impactDescription: Ensures backwards compatibility for API consumers
tags: api, versioning, nestjs
---
## Паспорт документа

- Статус документа: living standard
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
- Область применения: внутренние rule/reference-card документы для инженерной команды
- Связанные документы:
  - [Индекс Agents](../README.md)
  - [Команды разработки](../commands.md)
  - [Инженерные принципы](../../governance/engineering-principles.md)

## API Versioning Strategy

**Impact: MEDIUM**

Use URL-based versioning for the REST API. Current version is v1.

### URL Structure

```
/api/v1/catalog
/api/v1/items/:slug
/api/v1/auth/login
/api/v1/seller/items
/api/v1/admin/moderation
```

### NestJS Configuration

```typescript
// main.ts
app.setGlobalPrefix('api/v1');
```

### Rules for API Changes

- **Non-breaking changes** (add new fields, new endpoints): No version bump needed
- **Breaking changes** (remove fields, change response shape): Create new version
- **Deprecation**: Mark old endpoints as deprecated, keep working for at least 3 months
- Never remove or rename existing response fields — add new ones instead