Mosmoxmosmox

Mosmox journal

У фокусі — API.

Добірка публікацій, об’єднаних тегом «API».

Проєктування API для мобільного клієнта: пагінація, версіонування, помилки

Проєктування API для мобільного клієнта: пагінація, версіонування, помилки

Вебклієнт і бекенд зазвичай оновлюються одночасно: задеплоїли — і всі користувачі отримали нову версію. З мобільним застосунком так не буває. У продакшні одночасно живуть версії, випущені півтора року тому, пристрої в метро з нестабільним 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 / pageCursor (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», а не падає.

Політика підтримки версій

  1. Клієнт передає версію застосунку і платформу в кожному запиті (наприклад, заголовок X-App-Version). Це дає статистику і змогу вибірково змінювати поведінку.
  2. Визначте мінімальну підтримувану версію і термін: наприклад, підтримуємо версії за останні 12 місяців.
  3. Реалізуйте м'яке і жорстке оновлення: ендпоінт конфігурації повертає min_supported і recommended версії. На Android для цього є In-App Updates API, на iOS — власний екран з переходом в App Store.
  4. Перш ніж вимикати стару версію 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 token401Оновити токен і повторити запит один раз
Товар закінчився під час оформлення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 перед релізом

  1. Курсорна пагінація з детермінованим сортуванням і явною ознакою кінця.
  2. Політика версіонування й мінімальна підтримувана версія застосунку задокументовані.
  3. Ендпоінт конфігурації з min_supported версією є вже в першому релізі.
  4. Єдиний формат помилок (RFC 9457), машиночитні коди, request id.
  5. Idempotency-Key для всіх неідемпотентних операцій із грошима й замовленнями.
  6. Клієнт ігнорує невідомі поля і обробляє невідомі значення enum.
  7. OpenAPI-схема в репозиторії, перевірка зворотної сумісності в CI.
  8. 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.

Журнал

Ідеї та продукти

Android Calendar і Baseline Profiles: як оптимізація запуску зменшує зависання

Android Calendar і Baseline Profiles: як оптимізація запуску зменшує зависання

Верифікація розробників Android: глобальний запуск у січні 2027 і чек-ліст для команди

Верифікація розробників Android: глобальний запуск у січні 2027 і чек-ліст для команди