API Versioning

Стратегия версионирования, deprecation policy, Sunset header.

NurCore API использует path-based versioning. Текущая стабильная версия — v1, доступная по префиксу /api/v1/.

Текущая версия

https://api.nurcore.kg/api/v1/...

Все примеры в этой документации относятся к v1. Версия часть пути, а не заголовка — это упрощает кеширование, routing на API Gateway и debugging.

Принципы версионирования

Что не ломает совместимость (v1 остаётся)

Добавление новых endpoints
Добавление новых опциональных полей в request body
Добавление новых полей в response (клиенты должны игнорировать неизвестные поля)
Добавление новых query параметров с default значением
Добавление новых enum значений (клиент должен иметь fallback)
Bug fixes, security patches
Расширение rate-limits (только в сторону увеличения)

Что ломает совместимость (требует v2)

Удаление endpoint или поля в response
Переименование полей
Изменение типа поля (string → integer и т.п.)
Изменение обязательных полей в request
Изменение HTTP метода или статус-кодов
Уменьшение rate-limits

Deprecation Policy

При планировании breaking change endpoint помечается как deprecated минимум за 6 месяцев до отключения.

Sunset header

Deprecated endpoints возвращают RFC 8594 Sunset header:

HTTP/1.1 200 OK
Sunset: Sat, 12 Nov 2026 00:00:00 GMT
Deprecation: @1731369600
Link: <https://docs.nurcore.kg/docs/migration/v2>; rel="successor-version"
Warning: 299 - "Endpoint deprecated. See Link header for v2 migration."

Клиенты должны мониторить:

Sunset — дата отключения (ISO 8601 / HTTP date)
Deprecation — Unix timestamp когда endpoint стал deprecated
Link rel="successor-version" — куда мигрировать

Lifecycle endpoint

[Released]          → стабильный, версионируется по правилам выше
   ↓ 6 месяцев до v2
[Deprecated]        → возвращает Sunset header, продолжает работать
   ↓ к Sunset дате
[Sunset / Removed]  → возвращает 410 Gone (или редирект на v2)

Параллельная работа v1 + v2

Когда v2 будет выпущена:

https://api.nurcore.kg/api/v1/bookings/     ← v1 (deprecated)
https://api.nurcore.kg/api/v2/bookings/     ← v2 (stable)

Оба префикса работают параллельно минимум 6 месяцев. После Sunset v1:

v1 endpoints возвращают 410 Gone с подсказкой мигрировать
v2 endpoints остаются текущими

Что не считается breaking change в practice

Изменение	Версия	Причина
Новое поле в response	v1 OK	Клиенты должны игнорировать unknown поля
Расширение enum (`status`: добавление `IN_REVIEW`)	v1 OK	Клиент должен иметь default branch
Smarter rate-limit (был 60/min, стал 100/min)	v1 OK	Только увеличение
Smarter cache (был 60s, стал 300s)	v1 OK	Прозрачно для клиента
Дополнительный HTTP status code (был только 200/404, добавили 409)	v1 OK	Клиент должен handle generic 4xx

Best practice для клиентов: тестировать с unknown полями в response и default-branch в switch'ах.

Что считается breaking change

Изменение	Версия	Workaround
Удаление поля `passenger.age`	v2	До v2 — return default (0) или omit
Переименование `total_amount` → `total_price`	v2	До v2 — дублировать оба поля
Required → Optional	v1 OK	Совместимо
Optional → Required	v2	Только в v2 с migration path
Изменение URL (`/bookings/` → `/orders/`)	v2	Alias в v2 для compat

Header-based опции (без bumping версии)

Некоторые изменения можно прятать за opt-in headers в рамках v1:

`Accept-Version: v1.1`

Для feature toggles внутри v1:

GET /api/v1/bookings/abc?Accept-Version=v1.1

→ возвращает новый формат с расширенными полями (опционально).

`X-Experimental-Features: pricing_v2,inventory_v2`

Доступ к экспериментальным фичам без bumping path версии. Возвращается заголовок X-Experimental-Applied: pricing_v2.

Что NurCore не будет ломать

✅ Структура booking_reference (всегда 6 alphanumeric uppercase)
✅ UUID v4 формат для всех ID
✅ ISO 8601 для дат/времён (с timezone)
✅ HTTP 4xx body shape: {detail: string | object}
✅ Magic-link access_token срок жизни (24 часа) и binding (один booking)
✅ Rate-limit headers (X-RateLimit-Remaining, X-RateLimit-Reset)
✅ x-request-id на каждом ответе

Что будет в v2 (планы)

Будут breaking changes — каждый ниже требует bumping версии:

Область	Изменение
Booking	`total_amount` → `pricing.net` (вложенный объект с breakdown)
Passenger	`gender` enum: `male/female` → `male/female/x/u` (ICAO 9303)
Schedule	`flight_date` → `scheduled_departure` (timezone-aware datetime)
Auth	API key shape: `pk_live_` → `apk_pubX_` (новые префиксы)
Errors	`{detail: ...}` → RFC 9457 Problem Details (`{type, title, status, detail}`)

Roadmap v2: не раньше Q2 2027. До этого все изменения — non-breaking в v1.

Мониторинг deprecation

В каждом ответе, который уже deprecated, будут заголовки:

curl -i "https://api.nurcore.kg/api/v1/old-endpoint"

HTTP/1.1 200 OK
Sunset: Sat, 12 Nov 2026 00:00:00 GMT
Warning: 299 - "Use /api/v2/new-endpoint instead"

Best practice клиента:

function checkDeprecation(response: Response) {
  const sunset = response.headers.get("sunset");
  if (sunset) {
    const sunsetDate = new Date(sunset);
    const daysLeft = (sunsetDate.getTime() - Date.now()) / 86400_000;
    if (daysLeft < 30) {
      alert(`API будет отключён через ${Math.floor(daysLeft)} дней`);
      logToMonitoring("deprecation_warning", { sunset });
    }
  }
}

Уведомления о deprecation

Когда endpoint будет помечен как deprecated:

Email на developers@nurcore.kg (registered API key контакт)
Webhook api.deprecated (если настроен)
Banner на docs.nurcore.kg за 30 дней до Sunset
Changelog на https://docs.nurcore.kg/changelog

Подписаться на changelog — RSS feed: https://docs.nurcore.kg/feed.xml

FAQ

Что если я не успею мигрировать до Sunset?

Можно запросить продление через partners@nurcore.kg. По умолчанию — нет, но в исключительных случаях возможна доп. 60-дневная отсрочка для конкретного client_id.

Могу ли я зависнуть на v1 навсегда?

Нет. v1 будет отключена когда v2 будет стабильна (минимум 6 месяцев после v2 GA). Это для безопасности — старые endpoints могут содержать security gaps.

Как тестировать v2 до GA?

После анонса v2 будет доступна в sandbox с префиксом /api/v2-beta/. Стабильность не гарантирована, но breaking changes между beta и GA минимизируются.

Связанные документы

Authentication — API key format
Rate Limits — rate-limit headers
Error Handling — error response shape

On this page