Что такое REST API: принципы работы, HTTP-методы и примеры применения

Что такое REST API и как расшифровывается это название

REST API расшифровывается как Representational State Transfer Application Programming Interface — «передача представления состояния» плюс «интерфейс прикладного программирования». Главное уточнение: REST — это архитектурный стиль, а не протокол и не стандарт. Его сформулировал Рой Филдинг в диссертации Калифорнийского университета Ирвина в 2000 году. Лежащий в основе протокол HTTP стандартизирован документом RFC 7231 (IETF).

Сегодня REST использует более 80% публичных API в мире — это стандарт де-факто веб-разработки благодаря простоте, поддержке формата JSON (JavaScript Object Notation, формат обмена данными) и стандартным HTTP-методам. Разграничение терминов: REST — набор принципов; RESTful — API, которое им следует. На практике оба слова употребляют как синонимы.

Принципы REST API: шесть архитектурных ограничений

Рой Филдинг сформулировал шесть ограничений (constraints), которым должна соответствовать система, чтобы считаться RESTful. Именно они обеспечивают REST API предсказуемость, масштабируемость и независимость компонентов — то, что отличает архитектурный стиль от обычного HTTP-вызова.

Клиент-серверная архитектура и принцип отсутствия состояния

Первый принцип: пользовательский интерфейс отделён от данных — клиент и сервер развиваются независимо. Второй — stateless (отсутствие состояния): каждый запрос самодостаточен, сервер не хранит контекст сессии. Именно stateless обеспечивает горизонтальное масштабирование: новые инстансы добавляются без рассинхронизации. JWT-токен (JSON Web Token, веб-токен формата JSON) — типичное решение: он самодостаточен и не требует серверного хранилища сессий.

Кэширование, многослойность и единообразный интерфейс

Третий принцип — кэширование: GET-ответы помечаются заголовками Cache-Control и ETag, нагрузка на базу данных снижается в разы. Четвёртый — единообразный интерфейс: стандартный доступ через HTTP делает API предсказуемым для любого клиента. Пятый — многослойность: API-шлюз, балансировщик и прокси прозрачны для клиента. Шестой — Code on Demand — необязателен; в бэкенд-API практически не применяется.

HTTP-методы REST API: GET, POST, PUT, PATCH, DELETE

REST реализует операции создания, чтения, обновления и удаления данных (CRUD — Create, Read, Update, Delete) через стандартные HTTP-методы. Правило: действие определяет метод, а не URL — ресурс именуется существительным во множественном числе. Антипаттерн: POST /api/deleteTask; правильно: DELETE /api/tasks/1. Эндпоинт (endpoint, конечная точка) — конкретный URL ресурса, к которому обращается клиент.

Таблица методов: назначение, идемпотентность и статус-коды успеха

PUT заменяет ресурс целиком — PATCH обновляет только изменившиеся поля. Код 422 Unprocessable Entity возвращается, когда данные синтаксически корректны, но бизнес-логика их отклоняет.

Как работает REST API: запрос, ответ и статус-коды

Цикл обмена: клиент формирует HTTP-запрос (метод + URI + заголовки + тело) и отправляет на сервер; сервер возвращает HTTP-ответ (статус-код + заголовки + тело в формате JSON).

Заголовки запроса: Authorization: Bearer {token} — передача JWT; Content-Type: application/json — тип данных. Заголовки ответа: Cache-Control: max-age=3600; ETag: «abc123» — версия ресурса для условных запросов.

Группы статус-кодов: 2xx — успех, 3xx — редирект, 4xx — ошибка клиента, 5xx — ошибка сервера. Ключевые: 200 OK, 201 Created, 204 No Content, 400, 401, 403, 404, 422, 500. Структура тела ошибки: {«error»: {«code»: 404, «message»: «Not found», «timestamp»: «…»}}. Правильные статус-коды снижают нагрузку на базу данных на 80% — клиент понимает результат из кода ответа, не делая лишних запросов к серверу.

REST против SOAP и GraphQL: когда выбирать каждый подход

REST — не единственный архитектурный стиль. Конкуренты: SOAP (1998, Microsoft) и GraphQL (2015, компания Meta, признанная экстремистской и запрещённая в России).

REST проще SOAP: меньше кода, быстрее интеграция. GraphQL устраняет избыточную выборку данных (over-fetching) — полезно, когда клиенту нужна лишь часть полей ресурса: REST — для публичных API и небольших команд; SOAP — для корпоративных интеграций; GraphQL — для сложных мобильных приложений и одностраничных сайтов (SPA).

Если проектирование информационных систем вас интересует как профессия, в рамках федерального проекта «Активные меры содействия занятости» доступна программа «Системный аналитик: с нуля до проектирования систем» — 72 часа онлайн, бесплатно, зарплата выпускника от 130 000 ₽.

Модель зрелости Ричардсона: как оценить зрелость своего REST API

Леонард Ричардсон предложил фреймворк оценки соответствия API принципам REST. Модель зрелости Ричардсона включает четыре уровня:

• Уровень 0. HTTP как транспорт, один эндпоинт: POST /api {«action»: «placeOrder»}. Фактически вызов удалённых процедур (RPC) поверх HTTP.
• Уровень 1. Разные URL для ресурсов, один HTTP-метод (POST).
• Уровень 2. Правильные HTTP-методы и статус-коды: GET /orders/1 → 200 OK. Золотой стандарт продакшена.
• Уровень 3. HATEOAS (Hypermedia As The Engine Of Application State): тело ответа содержит ссылки на доступные действия с ресурсом.

Уровень 2 — оптимальный выбор для большинства проектов. HATEOAS редко оправдан: усложняет клиент без явной практической выгоды.

Безопасность REST API: API-ключи, OAuth 2.0 и JWT

Три механизма защиты — в порядке возрастания сложности:

API-ключи. Передаются в заголовке X-API-Key. Подходят для публичных API с базовой защитой — просты в реализации.

OAuth 2.0. Делегированная авторизация: пользователь открывает приложению доступ без передачи пароля — как вход через ВКонтакте. Выдаёт токены доступа с ограниченным сроком действия.

JWT. JSON Web Token — самодостаточный токен вида header.payload.signature: заголовок, полезная нагрузка, подпись. Каждый инстанс проверяет подпись самостоятельно — горизонтальное масштабирование без серверных сессий. HTTPS обязателен при любом механизме аутентификации.

Инструменты для тестирования и документирования REST API

• Postman — графический интерфейс для отправки запросов, создания коллекций и документирования API. Идеален для ручного тестирования.
• curl — утилита командной строки в Linux/macOS: проверка REST API одной командой из терминала.
• Swagger / OpenAPI — стандарт описания API с автогенерацией документации; встроен в FastAPI и Spring Boot.
• Insomnia — минималистичная альтернатива Postman для разработчиков, предпочитающих лаконичный интерфейс.

Примеры применения REST API: от Python до CRM

REST API — универсальный интерфейс: его применяют в веб-приложениях, мобильных сервисах, устройствах интернета вещей (IoT), микросервисных архитектурах и корпоративных системах. Системный аналитик работает с REST API ежедневно — проектирует эндпоинты, описывает контракты, координирует интеграции между командами разработки.

REST API на Python: пример с библиотекой requests

Библиотека requests — стандартный инструмент для работы с REST API в Python. Простейший GET-запрос:

import requests

headers = {«Authorization»: «Bearer YOUR_TOKEN»}

response = requests.get(«https://api.example.com/tasks», headers=headers)

data = response.json()

print(data)

Функция requests.get() отправляет запрос, response.json() парсит JSON-ответ. Python потребляет REST API через простой клиентский вызов. Для асинхронных проектов на FastAPI используют библиотеку httpx.

REST API в Bitrix24: российский CRM-кейс

Bitrix24 предоставляет официальный REST API для внешних интеграций. Метод call() позволяет создавать и обновлять сделки, задачи и контакты из внешних приложений. Типовые сценарии: синхронизация данных CRM, автоматическое создание задачи по заявке с сайта, интеграция с мессенджерами. API опубликован в официальной документации Bitrix24 на русском языке.

Часто задаваемые вопросы

Чем REST API отличается от API вообще?

API (Application Programming Interface) — общее понятие для любого интерфейса между программами. REST API — конкретный архитектурный стиль реализации через HTTP. Существуют и другие подходы: SOAP, GraphQL, gRPC. REST стал самым распространённым — более 80% публичных API — благодаря простоте реализации и поддержке стандартных HTTP-методов.

В чём разница между REST и RESTful?

REST — набор архитектурных принципов, описанных Роем Филдингом. RESTful — прилагательное для API, которое им следует: stateless, единообразный интерфейс, клиент-серверная разделённость. На практике термины используют взаимозаменяемо. Если система соответствует шести ограничениям Филдинга — она RESTful.

Чем FastAPI отличается от REST API?

FastAPI — Python-фреймворк для создания REST API, а не его альтернатива. REST API — архитектурный стиль; FastAPI — инструмент его реализации. Аналогично Spring Boot создаёт REST API на Java. Разница проста: REST описывает принципы, FastAPI их воплощает.

REST API — синхронный или асинхронный?

HTTP-запросы в REST синхронны по умолчанию: клиент ждёт ответа сервера. Асинхронное взаимодействие реализуют через вебхуки (webhooks) — сервер уведомляет клиента при наступлении события — или периодический опрос (polling). Для большинства API синхронная модель достаточна.

Обязателен ли JSON для REST API?

Нет. REST не требует конкретного формата данных. Сервер возвращает JSON, XML, HTML или plain text — формат указывается в заголовке Content-Type. JSON стал стандартом де-факто: он компактнее XML и нативно поддерживается в JavaScript.

Нужна ли авторизация в REST API?

REST не требует авторизации по умолчанию. Большинство продакшен-API защищены: API-ключами (простейший вариант), OAuth 2.0 (делегированный доступ) или JWT-токеном (stateless-аутентификация). Данные всегда передаются через HTTPS — это обязательно при любом механизме защиты.

Что такое модель зрелости Ричардсона?

Фреймворк Леонарда Ричардсона оценивает REST API по четырём уровням: 0 — HTTP как транспорт, 1 — разные URL для ресурсов, 2 — правильные HTTP-методы и статус-коды, 3 — HATEOAS. Уровень 2 — золотой стандарт продакшена. HATEOAS редко оправдан на практике — усложняет клиент без явной пользы.

Как работать с REST API на Java?

В Java REST API потребляют через OkHttp или встроенный HttpClient. На стороне сервера популярен Spring Boot — генерирует REST API с минимальным кодом и встроенной Swagger-документацией. Java и Spring Boot создают REST API так же, как Python и FastAPI: архитектурный стиль не зависит от языка реализации.