REST API: что это и как работает

REST API — самый распространенный способ, которым приложения обмениваются данными через интернет: мобильное приложение банка, сайт интернет-магазина, интеграция CRM с телефонией, бот в мессенджере почти наверняка работают через REST. Термин упоминают в вакансиях разработчиков, тестировщиков и аналитиков, но объясняют редко, а путаницы вокруг него много: REST называют протоколом, стандартом и технологией, хотя это ни то, ни другое, ни третье. Ниже что такое REST и API, принципы, из которых складывается REST, методы, запросы, ответы и коды, пример обмена данными, аутентификация, версии, документация, сравнение с SOAP, GraphQL и gRPC и вопросы, которые задают о REST на собеседованиях.

Курсы по backend-разработке и тестированию:

• Обучение FastAPI — Skillbox, 70 000 ₽

• Онлайн-курс по Django — Бруноям, 59 800 ₽

• Инженер по ручному тестированию — Яндекс Практикум, 94 000 ₽

• Системный аналитик с нуля до PRO — Академия Эдюсон, 161 800 ₽

• Все курсы по backend-разработке — программы в каталоге РБК

Что такое API и что такое REST

API, Application Programming Interface — это набор правил, по которым одна программа обращается к другой: какие запросы можно отправить, в каком формате, что придет в ответ. Приложение погоды не хранит прогноз само, оно запрашивает его у сервера метеослужбы через API.

REST, Representational State Transfer — это архитектурный стиль, то есть набор ограничений для построения веб-сервисов. Его описал Рой Филдинг в 2000 году в диссертации об архитектуре сетевых приложений, обобщив принципы, на которых уже работал веб. REST не протокол и не стандарт: нет документа, которому сервис обязан соответствовать, есть принципы, которым он следует в большей или меньшей степени.

REST API — это API, построенный по принципам REST поверх протокола HTTP. Сервер предоставляет ресурсы, у каждого ресурса есть адрес, а клиент работает с ресурсами стандартными методами HTTP. Сервис, который строго следует всем ограничениям REST, называют RESTful, на практике слова REST API и RESTful API используют как синонимы.

Принципы REST

Филдинг сформулировал шесть ограничений. Пять обязательных, одно по желанию.

1. Клиент-сервер. Клиент отвечает за интерфейс, сервер за данные и логику. Их можно разрабатывать и менять независимо, пока не меняется интерфейс между ними.

2. Отсутствие состояния, stateless. Каждый запрос содержит все, что нужно для его выполнения: сервер не помнит предыдущие запросы клиента. Данные авторизации передаются в каждом запросе. Благодаря этому запросы можно распределять между любыми серверами.

3. Кэширование. Ответ сервера явно помечается как кэшируемый или нет. Клиент или промежуточный узел может сохранить кэшируемый ответ и не ходить за ним повторно.

4. Единообразие интерфейса. Ресурсы идентифицируются адресами, с ними работают через их представления, обычно JSON, сообщения описывают сами себя через заголовки, а ответы содержат ссылки на связанные действия. Это ограничение главное и чаще всего нарушаемое.

5. Многоуровневая система. Между клиентом и сервером могут стоять балансировщики, прокси, шлюзы, кэши. Клиент об этом не знает и не должен знать.

6. Код по запросу, необязательное ограничение. Сервер может отправить клиенту исполняемый код, например скрипт. На практике в API почти не используется.

Когда говорят, что API «не совсем REST», обычно имеют в виду нарушения четвертого и второго пунктов: адреса, похожие на вызовы функций, или сессии на сервере.

Ресурсы и адреса

В REST все, с чем работает клиент, — это ресурсы: пользователь, заказ, товар, список заказов. У каждого ресурса есть уникальный адрес, URI. Правила именования сложились на практике и стали негласным стандартом:

• существительные во множественном числе, не глаголы: /orders, а не /getOrders;

• конкретный объект по идентификатору: /orders/1042;

• вложенность для связанных ресурсов: /users/7/orders — заказы пользователя 7;

• фильтры, сортировка и пагинация в параметрах запроса: /orders?status=paid&sort=-created_at&page=2;

• строчные буквы и дефисы, без расширений файлов и версий внутри адреса ресурса.

Действие над ресурсом задается не адресом, а HTTP-методом. Один адрес /orders/1042 обслуживает и чтение, и изменение, и удаление заказа.

Методы HTTP в REST API

Безопасный метод не меняет данные на сервере. Идемпотентный метод при повторении дает тот же результат, что и при однократном вызове: удалить заказ дважды все равно что удалить один раз, а вот создать заказ дважды значит получить два заказа. Эти свойства важны при обрывах связи: безопасный и идемпотентный запрос можно смело повторить, POST повторять опасно.

Еще два метода встречаются реже: HEAD возвращает только заголовки без тела, OPTIONS сообщает, какие методы поддерживает ресурс, его используют браузеры для проверок перед межсайтовыми запросами.

Из чего состоит запрос и ответ

Запрос клиента содержит четыре части:

• строка запроса: метод и адрес, например POST /orders;

• заголовки: формат данных Content-Type: application/json, ожидаемый формат ответа Accept, данные авторизации Authorization, служебные поля;

• параметры адреса: после знака вопроса, для фильтров и пагинации;

• тело: данные для создания или изменения ресурса, обычно в JSON. У GET и DELETE тела обычно нет.

Ответ сервера содержит код состояния, заголовки и тело. Тело для данных обычно в JSON, реже XML; формат согласуется через заголовки. Пример тела ответа на запрос заказа:

• id: 1042

• status: "paid"

• total: 3490

• items: список позиций с полями product_id, quantity, price

• created_at: "2026-11-09T10:15:00Z"

• links: ссылки на связанные ресурсы, например на пользователя и на отмену заказа

Последнее поле со ссылками реализует принцип HATEOAS из единообразного интерфейса: клиент узнает о возможных действиях из ответа, а не из документации. На практике его реализуют немногие API, и отсутствие ссылок не мешает называть API REST.

Коды состояния HTTP

Код ответа сообщает результат до разбора тела. Группы: 2xx успех, 3xx перенаправление, 4xx ошибка клиента, 5xx ошибка сервера. Коды, которые нужно знать при работе с REST API:

Полный перечень кодов с описанием ведет справочник MDN. Хорошо спроектированный API возвращает вместе с кодом 4xx тело с описанием ошибки: код ошибки в терминах сервиса, человекочитаемое сообщение и, для ошибок валидации, список полей.

Как работает REST API: пример

Клиент, мобильное приложение магазина, оформляет заказ. Последовательность обмена с сервером выглядит так.

1. Приложение отправляет POST /orders с заголовками Content-Type: application/json и Authorization: Bearer <токен> и телом, где перечислены товары и адрес доставки.

2. Сервер проверяет токен, валидирует тело, создает заказ в базе и отвечает кодом 201 Created, заголовком Location: /orders/1042 и телом с данными заказа.

3. Приложение показывает пользователю номер заказа и через минуту отправляет GET /orders/1042, чтобы обновить статус. Сервер отвечает 200 OK и текущим состоянием.

4. Пользователь меняет адрес доставки. Приложение отправляет PATCH /orders/1042 с телом, где только поле address. Сервер отвечает 200 OK и обновленным заказом.

5. Пользователь отменяет заказ. Приложение отправляет POST /orders/1042/cancel или DELETE /orders/1042, в зависимости от того, как спроектирован API: отмена как действие над ресурсом или как удаление. Сервер отвечает 200 или 204.

Каждый запрос самодостаточен: сервер не хранит сессию приложения, а узнает пользователя по токену в заголовке. Если на шаге 3 связь оборвалась, GET можно повторить без последствий. Если оборвалась на шаге 1, повторный POST создаст второй заказ, поэтому зрелые API принимают в заголовке ключ идемпотентности: уникальный идентификатор запроса, по которому сервер распознает повтор.

Аутентификация и безопасность

REST API без состояния, поэтому каждый запрос должен подтверждать, от кого он. Распространенные способы:

• API-ключ — постоянная строка, которую выдает сервис и которую клиент передает в заголовке. Просто, но ключ нельзя ограничить по времени, и его утечка дает полный доступ. Подходит для серверных интеграций.

• Токены Bearer, чаще всего JWT — клиент получает подписанный токен после входа и передает его в заголовке Authorization. Токен содержит данные пользователя и срок жизни, сервер проверяет подпись без обращения к базе.

• OAuth 2.0 — протокол, по которому пользователь разрешает одному сервису доступ к своим данным в другом без передачи пароля. Так работают кнопки «Войти через» и интеграции с внешними сервисами.

Базовые требования безопасности: только HTTPS, проверка прав на каждый ресурс, а не только факта входа, валидация всех входящих данных, лимиты на число запросов с ответом 429, отсутствие чувствительных данных в адресах, потому что адреса попадают в логи.

Версионирование

API меняется, а старые клиенты продолжают работать, поэтому несовместимые изменения выпускают новой версией. Три подхода: версия в адресе /v1/orders, версия в заголовке Accept: application/vnd.shop.v2+json, версия в параметре запроса. Самый распространенный и наглядный первый, самый близкий к принципам REST второй. Совместимые изменения, добавление нового поля или нового метода, версию не меняют.

Пагинация, фильтрация, лимиты

Список из миллиона заказов целиком не отдают. Пагинация по страницам: ?page=3&per_page=50, по смещению: ?offset=100&limit=50, или курсорная: ?cursor=abc123, где курсор указывает на позицию в списке и не ломается при добавлении данных. Фильтры и сортировка передаются параметрами. В ответе на список обычно есть метаданные: общее число, ссылки на следующую и предыдущую страницы.

Лимиты на число запросов защищают сервер. При превышении приходит 429 с заголовком Retry-After, и клиент обязан подождать. Правильная стратегия повторов: экспоненциальная задержка с небольшим случайным разбросом, чтобы тысячи клиентов не ударили по серверу одновременно после восстановления.

Документация REST API

Стандарт описания REST API — спецификация OpenAPI, раньше известная как Swagger. Это файл в формате YAML или JSON, где перечислены все адреса, методы, параметры, схемы запросов и ответов, коды ошибок. По нему автоматически генерируются интерактивная документация, клиентские библиотеки и тесты. Если у сервиса есть OpenAPI-описание, это заметно упрощает интеграцию; если нет, документацию читают на сайте сервиса или восстанавливают по примерам.

Как тестируют REST API

Ручное тестирование ведут в клиентах вроде Postman или Insomnia и в командной строке через curl: отправляют запросы с разными параметрами, проверяют коды, тела и заголовки. Как устроен Postman и как в нем собирать коллекции запросов, РБК разбирал в отдельной статье. Автоматические тесты пишут на языках разработки с библиотеками для HTTP, они проверяют контракт API при каждом изменении кода. Проверяют не только успешные сценарии, но и ошибки: неверные данные, отсутствие прав, несуществующие ресурсы, превышение лимитов, повторные запросы.

REST, SOAP, GraphQL и gRPC

REST остается выбором по умолчанию для публичных API из-за простоты и совместимости с любым клиентом, остальные подходы берут под конкретные ограничения.

Частые ошибки при проектировании REST API

• Глаголы в адресах: /createOrder, /deleteUser. Действие должен задавать метод.

• Код 200 на все ответы, включая ошибки, с описанием ошибки внутри тела. Клиенты и мониторинг ориентируются на коды.

• Сессии на сервере вместо токенов в запросе. Ломается масштабирование.

• Отсутствие пагинации в списках. Работает на тестовых данных, падает на реальных.

• Изменение данных через GET. Нарушает безопасность метода, кэши и поисковые роботы начинают менять данные.

• Отсутствие версионирования. Первое же несовместимое изменение ломает всех клиентов.

• Чувствительные данные в параметрах адреса.

• Разные форматы ошибок в разных методах. Клиенту приходится обрабатывать каждый случай отдельно.

Кому нужно знать REST API

Backend-разработчики проектируют и реализуют API. Frontend- и мобильные разработчики пишут клиентов к ним. Тестировщики проверяют контракт, коды и обработку ошибок, в вакансиях тестировщиков требование «опыт тестирования REST API» встречается почти всегда. Системные аналитики описывают API в требованиях и спецификациях OpenAPI. Продакт-менеджеры и маркетологи сталкиваются с REST при настройке интеграций между сервисами, когда нужно прочитать документацию и понять, что возможно, а что нет.

Вопросы о REST API на собеседовании

Чем REST отличается от HTTP?
HTTP это протокол передачи данных, REST это стиль построения API поверх него. Можно использовать HTTP без REST, например с адресами-глаголами, и теоретически REST поверх другого протокола.

Что значит stateless?
Сервер не хранит состояние клиента между запросами, каждый запрос содержит все необходимое, включая данные аутентификации.

Чем PUT отличается от PATCH?
PUT заменяет ресурс целиком и идемпотентен, PATCH меняет часть полей и в общем случае идемпотентности не гарантирует.

Что такое идемпотентность и зачем она нужна?
Свойство операции давать одинаковый результат при повторении. Позволяет безопасно повторять запросы при сбоях сети.

Какой код вернуть при успешном создании ресурса? 201 Created с заголовком Location.

Чем 401 отличается от 403?
401 означает, что клиент не аутентифицирован или токен недействителен, 403 что клиент известен, но прав на ресурс у него нет.

Как передать фильтры и сортировку? Параметрами запроса после знака вопроса, не в теле GET и не в адресе ресурса.

Что такое HATEOAS?
Принцип, по которому ответ содержит ссылки на доступные действия, и клиент узнает о них из ответа, а не из документации.

Как версионировать API?
В адресе, в заголовке или в параметре; несовместимые изменения требуют новой версии, совместимые нет.

Когда вместо REST выбрать GraphQL или gRPC?
GraphQL когда клиентам нужны разные наборы полей и важно сократить число запросов, gRPC для быстрого обмена между внутренними сервисами.

На эти вопросы отвечают по-разному в зависимости от роли: от разработчика ждут деталей реализации, от тестировщика сценариев проверки, от аналитика умения описать контракт. Практику по всем трем направлениям дают программы по backend-разработке, тестированию и системной аналитике, где проектирование и проверка REST API входят в обязательную часть курса.