Розробка REST API для мобільного додатку

Розробка REST API для мобільного застосунку

REST API для мобільного застосунку — це не просто набір ендпоїнтів. Мобільний клієнт працює в умовах, яких немає у веб-клієнтів: нестійке з'єднання, обмежений трафік, багатовер сійність (в App Store живуть користувачі з версіями двохлітної давнини). Це впливає на архітектурні рішення з першого дня.

Проектування під мобільний клієнт

Гранулярність відповідей. Класична помилка — ендпоїнти, що повертають надто багато даних. Екран профілю не має тягти весь об'єкт користувача з вложеними зв'язками, якщо потрібні лише аватар та ім'я. BFF (Backend for Frontend) паттерн вирішує: окремий шар API, оптимізований під мобільні екрани. Альтернатива — параметр fields у запиті (?fields=id,name,avatar).

Пагінація. Offset-based (?page=2&limit=20) не підходить для feeds у реальному часі — при додаванні нових записів зміщення їжджає, користувач бачить дублі. Cursor-based (?after=eyJpZCI6MTIzfQ==) позбавлена цієї проблеми. Обов'язково повертати hasMore флаг та nextCursor у відповіді.

Версіонування API. Починайте з версії в URL (/api/v1/). Мобільний застосунок не оновлюється примусово — 15–20% користувачів залишаються на старих версіях місяцями. v1 мають жити паралельно з v2 як мінімум 6–12 місяців.

Сітьовий шар на клієнті

Android (Kotlin): Retrofit 2 + OkHttp + Kotlin Coroutines — установившийся стек. Interceptor в OkHttp для додавання Authorization заголовка, логування (лише в debug) та retry-логіки:

class AuthInterceptor(private val tokenProvider: TokenProvider) : Interceptor {
    override fun intercept(chain: Chain): Response {
        val request = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer ${tokenProvider.getToken()}")
            .build()
        val response = chain.proceed(request)
        if (response.code == 401) {
            tokenProvider.refresh()
            // retry з новим токеном
        }
        return response
    }
}

iOS (Swift): Нативна URLSession або Alamofire. Для типобезопасних запитів — моделі Codable. RequestInterceptor в Alamofire для автоматичного refresh токена аналогічний OkHttp Interceptor.

Flutter: пакет dio з Interceptor — логіка та ж. retrofit_dart генерує типобезопасний клієнт з анотацій за аналогією з Retrofit.

Обробка помилок

Структуровані коди помилок важливіші HTTP-статусів для клієнтської логіки:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with specified ID does not exist",
    "field": null
  }
}

code — машинночитаємий, клієнт робить switch по ньому. message — для розробника, не для користувача. Клієнт показує свої локалізовані рядки по code, а не сирий message з API.

Валідаційні помилки мають повертати field — назву поля, яке не пройшло перевірку. Це дозволяє підсвічувати конкретне поле у формі.

Кеширование та offline

HTTP-кеширование через Cache-Control та ETag знижує навантаження та прискорює UX. OkHttp підтримує HTTP-кеш з коробки з вказанням директорії та розміру. Але для offline-роботи потрібен окремий шар: Room (Android) або CoreData/SwiftData (iOS) як локальна копія даних. Repository паттерн розділяє джерела даних.

Безпека

• Certificate Pinning: OkHttp.CertificatePinner на Android, URLSessionDelegate з didReceive challenge на iOS. Усикладняє MITM-атаки, але вимагає плану ротації сертифікатів.
• Не зберігайте JWT в SharedPreferences (Android) або UserDefaults (iOS). Використовуйте EncryptedSharedPreferences / Keychain.
• HTTPS везде, без винятків. Немає cleartext у production.

Що входить у роботу

Проектуємо ендпоїнти з урахуванням мобільної специфіки, реалізуємо клієнтський сітьовий шар з interceptors, обробкою помилок та retry, налаштовуємо кеширование. Документуємо API через OpenAPI/Swagger для зручності мобільної команди.

Строк: 5–12 днів залежно від кількості ендпоїнтів та необхідності бекенду.