REST API: що це, HTTP методи та принцип роботи в мобільних застосунках

Що таке REST API?

REST API (Representational State Transfer API) — це архітектурний стиль, запропонований Роєм Філдінгом у його докторській дисертації в 2000 році. Він визначає набір обмежень та принципів для проєктування мережевих протоколів. API, що відповідає цим обмеженням, називають RESTful. REST не є протоколом або стандартом — це архітектурний підхід, який використовує існуючі протоколи (переважно HTTP) для обміну даними між клієнтом та сервером.

Ключова ідея REST — ресурсно-орієнтована архітектура. Замість виклику методів на сервері (як у SOAP або RPC) клієнт оперує ресурсами: отримує їх список, створює нові, оновлює або видаляє. Кожен ресурс — це сутність предметної області: користувач, замовлення, товар, стаття. Ресурс має стан, який передається клієнту в стандартизованому форматі, зазвичай JSON. Сервер не зберігає стан клієнта між запитами — це принцип stateless, ключова вимога REST.

Основні характеристики REST API:

• Stateless — кожен запит від клієнта містить всю інформацію, необхідну для його обробки
• Cacheable — відповіді сервера повинні бути явно позначені як кешовані або некешовані
• Layered system — архітектура може включати проміжні сервери, балансувальники навантаження, проксі
• Uniform interface — єдиний інтерфейс взаємодії через HTTP методи, URL та статус-коди

Принципи REST архітектури

REST базується на шести архітектурних обмеженнях, сформульованих Філдінгом. Дотримання цих обмежень гарантує масштабованість, продуктивність та простоту інтеграції. Кожен принцип вирішує конкретну проблему розподілених систем — від необхідності кешування до вимог безпеки. Розглянемо кожен принцип детально.

Принцип Uniform Interface додатково включає чотири під-обмеження: ідентифікація ресурсів через URI, маніпулювання ресурсами через представлення, самоописувані повідомлення та HATEOAS (гіпермедіа як двигун стану застосунку). Останнє під-обмеження часто ігнорується на практиці — більшість сучасних REST API не реалізують HATEOAS повною мірою, що веде до дискусій про те, чи є такий API “справжнім” RESTful.

Принцип Stateless — один з найважливіших для масштабування. Відсутність сесій на сервері означає, що будь-який екземпляр сервера може обробити будь-який запит. Це спрощує горизонтальне масштабування: достатньо додати нові сервери за балансувальником. Для мобільних застосунків stateless також означає, що запит може бути відправлений на будь-який сервер CDN, що критично для глобальної доступності.

HTTP методи в REST

Кожен HTTP метод в REST API відповідає певній операції над ресурсом: GET для читання, POST для створення, PUT для повного оновлення, PATCH для часткового оновлення, DELETE для видалення. Ідемпотентність методів — ключова характеристика: GET, PUT, DELETE — ідемпотентні (багаторазове виконання дає той самий результат), POST та PATCH — ні. Це важливо для обробки помилок мережі, коли клієнт не знає, чи дійшов запит до сервера.

• GET — отримання ресурсу або списку ресурсів. Ідемпотентний, не змінює стан сервера
• POST — створення нового ресурсу. Не ідемпотентний, кожен виклик створює новий ресурс
• PUT — повна заміна ресурсу. Ідемпотентний, повторний виклик не змінює стан після першого
• PATCH — часткове оновлення ресурсу. Частково ідемпотентний (залежить від реалізації)
• DELETE — видалення ресурсу. Ідемпотентний, повторне видалення повертає 404, а не помилку

Статус коди HTTP є невід’ємною частиною REST API. Кожен код несе певний сенс: 200 OK для успішного GET, 201 Created для POST, 204 No Content для DELETE без тіла відповіді, 400 Bad Request при невалідних даних, 401 Unauthorized при відсутності аутентифікації, 404 Not Found при відсутності ресурсу. Правильне використання статус-кодів робить API само-документованим та спрощує налагодження.

Формати даних: JSON та інші

JSON (JavaScript Object Notation) — основний формат передачі даних в REST API. Його популярність пояснюється простотою, людською читабельністю та нативною підтримкою в JavaScript. JSON передається з заголовком Content-Type: application/json. Альтернативи включають XML (громіздкий, застаріваючий), YAML (зручний для конфігурації, рідше для API) та Protocol Buffers (бінарний, ефективний для високонавантажених систем).

Структура JSON-об—єкта в REST API зазвичай включає поля id, type та атрибути ресурсу. Для колекцій використовується JSON-масив з метаданими пагінації. Сучасні REST API слідують специфікації JSON:API (jsonapi.org) або JSON Schema для валідації відповідей. Використання єдиного формату даних спрощує розробку клієнтських бібліотек та генерацію документації.

Приклад JSON-відповіді для списку користувачів:

{
    "data": [
        {
            "id": 1,
            "name": "Анна Петрова",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Вибір формату передачі даних впливає на продуктивність мобільного застосунку. JSON стискається через GZIP на 70-80%, що робить його прийнятним для більшості сценаріїв. Для real-time застосунків з великим обсягом даних (стрімінг, ігри) рекомендується переходити на бінарні протоколи або використовувати WebSocket в комбінації з Protocol Buffers.

Приклади REST API запитів

Розглянемо практичні приклади роботи з REST API на стороні мобільного застосунку. В якості прикладу візьмемо API для роботи з замовленнями в інтернет-магазині. Для кожного HTTP методу показано запит та очікувану відповідь сервера. Приклади демонструють типову структуру RESTful API, що використовується в мобільній розробці.

GET — отримання списку замовлень

Запит на отримання всіх замовлень користувача з пагінацією. Відповідь містить масив об—єктів замовлення та мета-інформацію для посторінкової навігації. Параметри page та per_page передаються через query string.

// Retrofit інтерфейс для REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — створення нового замовлення

Створення нового замовлення через POST запит. Сервер повертає статус 201 Created та створений об—єкт в тілі відповіді. Важливо: створення йде на колекцію /api/v1/orders, а не на конкретний ресурс — це стандартний RESTful патерн.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Приклад тіла запиту
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — видалення замовлення

Видалення ресурсу виконується методом DELETE за конкретним URL замовлення. Успішне видалення повертає 204 No Content. Ідемпотентність DELETE означає, що повторний запит до того ж URL поверне 404 Not Found, що коректно обробляється на клієнті.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Використання в ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Ці приклади демонструють типову реалізацію REST API на стороні Android з використанням Retrofit та Kotlin Coroutines. Для iOS-застосунків аналогічну роль виконує URLSession або бібліотека Alamofire в зв’язці з Codable-протоколами. Структура REST API залишається однаковою незалежно від платформи — змінюється лише спосіб виконання запитів.

RESTful API дизайн: практичні рекомендації

Проєктування якісного RESTful API вимагає дотримання угод, які роблять API інтуїтивно зрозумілим для розробників. Ресурси повинні іменуватися іменниками у множині (/users, /orders, /products), HTTP методи відображати операції, а URL — ієрархію вкладеності. Помилки повинні повертати стандартизований JSON з кодом та повідомленням, а не просто HTTP статус. Дотримання цих конвенцій знижує поріг входу для нових розробників та спрощує інтеграцію.

• Іменування ресурсів — множина, kebab-case: /api/v1/user-orders, не /api/v1/getUserOrders
• Фільтрація та сортування — через query параметри: ?status=active&sort=created_at:desc
• Пагінація — курсорна для великих наборів, посторінкова для невеликих
• Версіонування — через URL (/api/v2/) або заголовок Accept-Version
• Помилки — єдиний формат: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — заголовки X-RateLimit-Remaining та Retry-After

Одна з частих помилок при проєктуванні REST API — надмірна вкладеність ресурсів. Замість /users/1/orders/5/items/3 краще використовувати пласку структуру з query-параметрами: /items?order_id=5&user_id=1. Це спрощує кешування, не вимагає підтримки довгих шляхів на сервері та легше документується. Пласка архітектура також краще сумісна з graph-based запитами при переході на GraphQL в майбутньому.

Безпека REST API реалізується через аутентифікацію (JWT, OAuth 2.0) та авторизацію на рівні ресурсів. Кожен запит повинен перевіряти, чи має користувач доступ до запитуваного ресурсу. HTTPS обов’язковий — без шифрування токени та дані передаються у відкритому вигляді. Для мобільних застосунків рекомендується використовувати OAuth 2.0 з PKCE (Proof Key for Code Exchange) для безпечного отримання токенів.

Версіонування та кешування

Версіонування REST API необхідне для зворотної сумісності при змінах. Найбільш поширені підходи: версія в URL (/api/v1/orders), версія в заголовку (Accept: application/vnd.myapi.v1+json) та версія в query-параметрі (?api_version=1). URL-версіонування — найпопулярніший метод, оскільки він явно видно в логах та документації. Однак він порушує принцип REST про єдиний URL ресурсу.

Кешування в REST API реалізується через HTTP заголовки Cache-Control, ETag та Last-Modified. GET-запити, позначені як кешовані, можуть обслуговуватися з кешу браузера або проксі без звернення до сервера. Для мобільних застосунків кешування особливо важливе — воно знижує витрати трафіку та прискорює відображення раніше завантажених даних при поганому з’єднанні. ETag — це хеш вмісту відповіді: клієнт відправляє його в If-None-Match, а сервер повертає 304 Not Modified, якщо дані не змінилися.

Сучасні альтернативи REST API включають GraphQL (гнучка вибірка даних клієнтом) та gRPC (бінарний протокол на HTTP/2 для мікросервісів). Однак REST залишається основним стандартом для публічних API завдяки своїй простоті, універсальності та широкій підтримці інструментів. Вибір між REST та альтернативами залежить від конкретних вимог проєкту: складності запитів, обсягу даних, вимог до real-time оновлень.