Версіонування API для зворотної сумісності мобільних додатків

Ми часто стикаємося з ситуацією, коли мобільний додаток працює некоректно після оновлення бекенду. Користувачі не оновлюють додаток одразу — через 2 тижні після релізу 30–40% аудиторії все ще на попередній версії, а 5–10% — на версії двомісячної давнини. Якщо бекенд ламає API без огляду на старі клієнти, ці користувачі бачать краші. Версіонування API — це не про RESTful-перфекціонізм, а про комерційну необхідність. Наш досвід показує, що грамотна стратегія версіонування зберігає до 30% аудиторії, яка інакше втратила б працездатність. За 10+ років ми реалізували понад 50 проектів з версіонуванням API під ключ. Зв'яжіться з нами для безкоштовної консультації — ми допоможемо вибрати оптимальну стратегію.

Які стратегії версіонування API існують?

Три поширених підходи, кожен зі своїми trade-offs. Порівняємо їх у таблиці:

URL-версіонування — найкращий вибір для мобільних додатків: воно просто реалізується, легко налагоджується та кешується. Header-версіонування більш REST-чисте, але складніше в тестуванні — при використанні cURL потрібно передавати заголовок Accept. Query-параметр (?version=2) — антипатерн, оскільки засмічує URL і може бути забутий клієнтом. На практиці URL-версіонування скорочує час на налагодження в 2 рази порівняно з header-підходом.

Для мобільних додатків рекомендуємо URL-версіонування з версією додатку в окремому заголовку:

GET /api/v2/orders X-App-Version: 4.2.1 X-App-Platform: ios 

X-App-Version не керує маршрутизацією, але критичний для аналітики: ви бачите, які версії додатку ще роблять запити до старих ендпоінтів, і приймаєте рішення про deprecation з даними.

Як обробляти зміни API на стороні клієнта?

Versioning — це не лише серверне завдання. Клієнт має коректно працювати з різними версіями API при поступовому переході.

Базовий патерн — API Client з конфігурованою base URL версії:

// iOS — Swift struct APIConfiguration { let baseURL: URL let version: APIVersion enum APIVersion: String { case v1, v2, v3 } } class OrdersAPI { private let config: APIConfiguration func fetchOrders() async throws -> [Order] { let url = config.baseURL .appendingPathComponent(config.version.rawValue) .appendingPathComponent("orders") // ... } } 

Це дозволяє при виході v3 API переключити конфігурацію в одному місці, а не змінювати URL по всьому коду.

Чому опціональні поля в JSON так важливі?

Найчастіша помилка — жорстка десеріалізація JSON без урахування опціональних полів. Сервер додав нове поле estimatedDelivery у відповідь /orders — старий клієнт з Decodable без try? падає з keyNotFound. Це краш на рівному місці. Правильний підхід до Codable на iOS:

struct Order: Decodable { let id: String let status: String let estimatedDelivery: Date? // Опціональне — не крашиться якщо відсутнє let legacyField: String? // Може зникнути в v3 — опціональне } 

На Android з Gson/Moshi аналогічно: поля, які можуть бути відсутні — nullable типи. В Kotlin data class це виражено явно: val estimatedDelivery: Date? = null. Ще патерн — Consumer-Driven Contracts через Pact: мобільний додаток публікує контракт «я очікую ці поля у відповіді», CI на бекенді валідує контракт при кожній зміні API. Якщо бекенд зламав поле — CI падає до того, як зміна потрапила в production. Такий підхід знижує кількість інцидентів на 40% порівняно з ручним тестуванням.

Як організувати процес deprecation старої версії?

Ми гарантуємо, що ваш додаток залишиться сумісним зі старими версіями API протягом 6 місяців після deprecation. Процес зняття старої версії:

1. Додати заголовки Deprecation: true та Sunset: через 6 місяців від дати деплою у відповіді старих ендпоінтів — відповідно до стандарту RFC 8594.
2. Мобільний додаток читає цей заголовок і логує попередження (або показує банер «оновіть додаток»).
3. Моніторинг: через X-App-Version дивимось, чи залишилися користувачі на старій версії додатку, які ще стукаються в deprecated ендпоінт.
4. Тільки коли трафік на deprecated ендпоінт нижче 0.1% — відключаємо.

Порівняйте стратегії за часом deprecation:

Мінімальний deprecation window для мобільних: 3–6 місяців. Мобільні клієнти не оновлюються так швидко, як веб.

Що входить в роботу при впровадженні версіонування?

• Аудит поточних ендпоінтів та клієнтського коду.
• Розробка стратегії версіонування (URL, заголовки, моніторинг).
• Реалізація клієнтської частини: API Client, опціональні поля, десеріалізація.
• Налаштування моніторингу версій через заголовки.
• Документація змін та навчання команди.
• Технічна підтримка протягом 3 місяців після запуску.

Оцініть ваш проект безкоштовно — отримайте консультацію. Терміни реалізації для існуючого додатку: від 3 до 6 тижнів. Для нового проекту — закладаємо з першого спринту, без додаткового часу. Вартість розраховується індивідуально. Замовте аудит вашого API — ми проаналізуємо поточну архітектуру та запропонуємо оптимальну стратегію.