Qadam Roadmap
← Назад к библиотеке
проектdocs/Agents/rules/api-versioning.md

api-versioning.md

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

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 документы для инженерной команды
  • Связанные документы:

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

// 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