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
• Пагинация — 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 и альтернативами зависит от конкретных требований проекта: сложности запросов, объёма данных, требований к real-time обновлениям.