REST API: принципы и отличие от других видов API

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

Принципы REST

REST строится вокруг ресурсов. Ресурс — это сущность, с которой работает система: клиент, заказ, товар, платёж. У каждого ресурса есть адрес, например /orders/123 для заказа с номером 123. Действия с ресурсами выражаются стандартными методами протокола HTTP:

• GET — получить данные
• POST — создать новый ресурс
• PUT или PATCH — изменить существующий
• DELETE — удалить

Результат запроса сообщается кодом статуса HTTP: успешное выполнение, ресурс создан, ресурс не найден, нет доступа, ошибка на сервере. Данные обычно передаются в формате JSON. Хороший REST API последовательно использует эти коды: клиентская программа по одному коду понимает, нужно ли исправить запрос или повторить его позже.

Отсутствие состояния

Каждый запрос к REST API самодостаточен: он содержит всё, что нужно серверу для обработки, включая данные авторизации. Сервер не помнит предыдущие запросы клиента. Это упрощает масштабирование: любой запрос может обработать любой экземпляр сервера.

Чем REST удобен

Он опирается на привычный HTTP, поэтому его поддерживают все языки программирования и инструменты. Запросы легко проверить даже в браузере или простой утилите. Структура предсказуема: зная адрес ресурса и метод, разработчик понимает, что произойдёт. Для большинства интеграций бизнеса — сайт с учётом, бот с CRM, приложение с сервером — REST подходит отлично.

SOAP

Более старый протокол для веб-сервисов. Сообщения передаются в формате XML со строгой схемой, описанной в отдельном документе. SOAP формальнее и тяжелее REST, но до сих пор встречается в банковских системах, государственных сервисах и корпоративных продуктах. Если внешняя система предлагает только SOAP, интеграция с ней вполне возможна, просто инструменты будут другими.

GraphQL

Язык запросов, при котором клиент сам указывает, какие поля ему нужны, и получает ровно их одним запросом. Удобен для сложных интерфейсов, где одному экрану нужны данные из многих сущностей. Сложнее в реализации на сервере и в кэшировании.

gRPC

Высокопроизводительный протокол для обмена между сервисами внутри системы. Данные передаются в компактном двоичном формате по строгим контрактам. Используется во внутренней архитектуре крупных систем, а для внешних интеграций с партнёрами применяется реже.

Вебхуки

Вебхук — не альтернатива REST, а дополнение. Вместо того чтобы постоянно спрашивать у сервиса «есть ли новые заказы», вы даёте ему адрес, и он сам отправляет запрос, когда событие произошло. Многие сервисы — платёжные системы, CRM, мессенджеры — сочетают REST API для запросов и вебхуки для событий.

Что выбирать

Для собственного публичного API — REST: его проще всего подключить партнёрам. Для внутренних высоконагруженных сервисов — можно рассмотреть gRPC. Для сложного клиентского интерфейса с большим количеством данных — GraphQL. При интеграции с чужой системой выбора обычно нет: используете то, что она предлагает.

Частая путаница

Не всякий API на HTTP с JSON действительно следует принципам REST. Встречаются интерфейсы, где все действия выполняются одним методом по одному адресу с названием операции в теле запроса. Это не плохо само по себе, но разработчику нужно читать документацию, а не полагаться на привычные правила REST.