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%, което го прави приемлив за повечето сценарии. За приложения в реално време с голям обем от данни (стрийминг, игри) се препоръчва преход към бинарни протоколи или използване на 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
• Пагинация cursor-based за големи множества, page-based за малки
• Версиониране чрез 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 и алтернативите зависи от конкретните изисквания на проекта: сложност на заявките, обем на данните, изисквания за актуализация в реално време.