Вебклієнт і бекенд зазвичай оновлюються одночасно: задеплоїли — і всі користувачі отримали нову версію. З мобільним застосунком так не буває. У продакшні одночасно живуть версії, випущені півтора року тому, пристрої в метро з нестабільним 3G і користувачі, які вимкнули автооновлення. API, спроєктований «як для сайту», перетворюється на постійне джерело збоїв і костилів у клієнті.
У цій статті ми розбираємо три теми, де мобільна специфіка відчувається найсильніше: пагінацію, версіонування і формат помилок. Плюс ідемпотентність, кешування і контракт між командами, без яких перші три не працюють.
Чим мобільний клієнт відрізняється від вебу
| Фактор | Веб | Мобільний застосунок | Наслідок для API |
|---|---|---|---|
| Версії клієнта | Одна актуальна | Десятки одночасно | Зворотна сумісність обов'язкова |
| Мережа | Переважно стабільна | Обриви, високі затримки, перемикання Wi-Fi/LTE | Ідемпотентність, повтори, малі відповіді |
| Оновлення | Миттєве | Через рев'ю і користувача | Логіку, яку треба змінювати, тримати на сервері |
| Ресурси | Десктопні | Батарея, трафік, пам'ять | Менше запитів, компактні payload |
| Життєвий цикл | Вкладка відкрита | Застосунок призупиняють і вбивають | Відновлення стану, повторне завантаження сторінок |
Головне правило: кожна зміна API має бути безпечною для найстарішої підтримуваної версії застосунку. Google формалізує, що вважається несумісною зміною, у AIP-180: видалення чи перейменування поля, зміна типу, нове обов'язкове поле в запиті, зміна значень за замовчуванням.
Пагінація: курсори замість сторінок
Offset-пагінація (?page=3&limit=20) проста, але на мобільних стрічках вона дає два класичні баги. Якщо між завантаженням першої і другої сторінки з'явилося нове замовлення, користувач побачить дублікат. Якщо запис видалили — один елемент пропаде. Плюс великі offset повільні на рівні бази.
Курсорна пагінація (keyset) передає непрозорий токен позиції: клієнт отримує next_cursor і відправляє його в наступному запиті. Цей підхід рекомендує Google в AIP-158 (page_token), а для GraphQL він стандартизований у специфікації Relay Connections.
| Критерій | Offset / page | Cursor (keyset) |
|---|---|---|
| Стабільність при вставках і видаленнях | Дублікати й пропуски | Стабільно |
| Продуктивність на глибоких сторінках | Деградує зі зростанням offset | Стабільна за наявності індексу |
| Перехід на довільну сторінку | Так | Ні (зазвичай не потрібен у мобільних стрічках) |
| Загальна кількість | Легко | Окремий, бажано кешований запит |
| Складність реалізації | Мінімальна | Помірна |
Практичні правила
- Курсор робіть непрозорим (наприклад, base64 від id і дати сортування), щоб змінювати реалізацію без зміни клієнта.
- Сервер визначає максимальний розмір сторінки; клієнт може попросити менше. Для мобільних списків зазвичай достатньо 20–50 елементів.
- Поверніть явну ознаку кінця: порожній next_cursor або has_more: false.
- Для pull-to-refresh додайте можливість запитати новіші за перший елемент записи, а не перезавантажувати весь список.
- Сортування має бути детермінованим: «за датою, потім за id», інакше записи з однаковою датою перемішуються між сторінками.
Версіонування: як не зламати старі застосунки
Існує три поширені підходи: версія в URL (/v2/orders), у заголовку (Accept або власний), або датовані версії, як у Stripe, де кожен клієнт закріплений за конкретною датою API. Для більшості мобільних продуктів ми рекомендуємо простий шлях: мажорна версія в URL і максимум адитивних змін усередині неї.
Адитивні зміни — безпечні
- Нове необов'язкове поле у відповіді. Клієнт має ігнорувати невідомі поля: перевірте, що JSON-декодер не падає на них (у Swift Codable і kotlinx.serialization це налаштування, а не поведінка за замовчуванням для всіх випадків).
- Новий ендпоінт або новий необов'язковий параметр запиту.
- Нове значення enum — лише якщо клієнт обробляє невідомі значення як «unknown», а не падає.
Політика підтримки версій
- Клієнт передає версію застосунку і платформу в кожному запиті (наприклад, заголовок X-App-Version). Це дає статистику і змогу вибірково змінювати поведінку.
- Визначте мінімальну підтримувану версію і термін: наприклад, підтримуємо версії за останні 12 місяців.
- Реалізуйте м'яке і жорстке оновлення: ендпоінт конфігурації повертає min_supported і recommended версії. На Android для цього є In-App Updates API, на iOS — власний екран з переходом в App Store.
- Перш ніж вимикати стару версію API, подивіться частку запитів від неї. Ми зазвичай чекаємо, доки вона опуститься нижче 1–2% активних користувачів, і попереджаємо про примусове оновлення заздалегідь.
Помилки: один формат для всього API
Найгірший варіант, який ми регулярно бачимо: 200 OK з {"success": false} у тілі, різні формати помилок у різних ендпоінтах і текст англійською, який клієнт показує користувачу як є. Стандарт RFC 9457 Problem Details (наступник RFC 7807) пропонує єдину структуру: type, title, status, detail, instance і довільні розширення.
Що потрібно мобільному клієнту від помилки
- Правильний HTTP-статус за RFC 9110: 400/422 — помилка вхідних даних, 401 — потрібна автентифікація, 403 — немає прав, 404 — немає ресурсу, 409 — конфлікт, 429 — забагато запитів, 5xx — проблема сервера.
- Машиночитний код (type або code), за яким клієнт вирішує, що робити: показати помилку біля поля, запропонувати повторити чи вийти з акаунта.
- Помилки валідації за полями, щоб підсвітити конкретне поле форми.
- Ідентифікатор запиту (request id) для пошуку в логах, коли користувач звертається в підтримку.
- Локалізований текст — за заголовком Accept-Language або на клієнті за кодом. Важливо, щоб відповідальність була визначена.
| Ситуація | Статус | Поведінка клієнта |
|---|---|---|
| Невалідний e-mail у формі | 422 + errors за полями | Підсвітити поле, не повторювати |
| Протермінований access token | 401 | Оновити токен і повторити запит один раз |
| Товар закінчився під час оформлення | 409 + код out_of_stock | Показати діалог і оновити кошик |
| Перевищено ліміт | 429 + Retry-After | Зачекати вказаний час, показати повідомлення |
| Збій сервера | 500/503 | Повторити з експоненційною затримкою, показати кешовані дані |
Ідемпотентність і нестабільна мережа
Користувач натиснув «Оплатити», запит дійшов до сервера, а відповідь загубилася в тунелі метро. Клієнт повторює запит — і створює друге замовлення. Рішення — ключ ідемпотентності: клієнт генерує UUID для операції і передає його в заголовку Idempotency-Key; сервер, отримавши повтор із тим самим ключем, повертає збережений результат. Так працює API Stripe, а заголовок проходить стандартизацію в IETF.
GET, PUT і DELETE за визначенням ідемпотентні, POST — ні. Тому ключ потрібен насамперед для створення замовлень, платежів, повідомлень і будь-яких операцій із грошима.
Продуктивність: менше запитів, менше байтів
- Агрегуйте дані під екран. Якщо головний екран робить 8 запитів при запуску, розгляньте ендпоінт, що повертає все потрібне одним викликом (патерн Backend for Frontend).
- Умовні запити. ETag і If-None-Match дозволяють серверу відповісти 304 Not Modified без тіла.
- Стиснення. gzip або brotli для JSON зменшує обсяг у рази.
- Розмір зображень. Віддавайте URL із параметрами розміру, а не оригінали на кілька мегабайт.
- Часові мітки. Усі дати в ISO 8601 з часовою зоною (UTC), форматування — на клієнті.
Контракт між бекендом і мобільною командою
Опис API у OpenAPI — не документація «для галочки», а контракт. З нього можна генерувати клієнтський код, mock-сервер для мобільних розробників (щоб вони не чекали бекенд) і контрактні тести, що ловлять несумісні зміни в CI. Практика, що добре працює в наших проєктах: будь-яка зміна схеми проходить рев'ю мобільного розробника, а CI автоматично порівнює нову схему з попередньою і блокує видалення полів.
Типові помилки
- Перейменування поля «бо так гарніше» без нової версії API.
- Offset-пагінація у стрічках, що часто оновлюються.
- Помилки зі статусом 200 і різні формати помилок у різних ендпоінтах.
- Відсутність механізму примусового оновлення до першого релізу: додати його пізніше в старі версії неможливо.
- Повтори POST-запитів без ключа ідемпотентності.
- Декодер у клієнті, що падає на невідомому полі чи значенні enum.
Чекліст API перед релізом
- Курсорна пагінація з детермінованим сортуванням і явною ознакою кінця.
- Політика версіонування й мінімальна підтримувана версія застосунку задокументовані.
- Ендпоінт конфігурації з min_supported версією є вже в першому релізі.
- Єдиний формат помилок (RFC 9457), машиночитні коди, request id.
- Idempotency-Key для всіх неідемпотентних операцій із грошима й замовленнями.
- Клієнт ігнорує невідомі поля і обробляє невідомі значення enum.
- OpenAPI-схема в репозиторії, перевірка зворотної сумісності в CI.
- ETag, стиснення і агреговані ендпоінти для ключових екранів.
Джерела: RFC 9457: Problem Details for HTTP APIs; RFC 9110: HTTP Semantics; Google AIP-158: Pagination; Google AIP-180: Backwards compatibility; GraphQL Cursor Connections Specification; Stripe: API versioning; Stripe: Idempotent requests; IETF: The Idempotency-Key HTTP Header Field; OpenAPI Specification; Android: In-app updates.



