Сравнение шести стилей API: REST, GraphQL, WebSockets, Webhooks, gRPC, SOAP

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

Если REST уже знаком вам, далее будет рассказано точно, когда следует сменить инструменты и почему.

Что такое API (один абзац, затем переходим дальше)

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

Оказывается, существует шесть различных вариантов таких «официантов», с которыми вы можете столкнуться.

REST: стандарт и его ограничения

REST, сокращение от Representational State Transfer, работает на основе HTTP и опирается на две ключевые идеи: URL, который идентифицирует нужный ресурс, и метод HTTP, описывающий действие, которое необходимо выполнить с ним.

Четыре метода покрывают практически все случаи: GET загружает данные, POST создаёт новую запись, PUT обновляет или заменяет существующую, а DELETE удаляет её. Основной особенностью REST является отсутствие состояния — сервер не сохраняет информацию о предыдущих взаимодействиях с пользователем. Любая необходимая контекстная информация должна включаться непосредственно в запрос каждый раз.

GET https://api.zomato.com/v1/restaurants?search=biryani
Authorization: Bearer <token>

После получения запроса сервер проверяет личность пользователя, извлекает соответствующие записи из базы данных и возвращает JSON-пакет.

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

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

GraphQL: запрашивайте ровно то, что вам нужно

У REST есть хорошо известная проблема — чрезмерное возвращение данных. При обращении к эндпоинту /user вы можете получить имя, фото профиля, возраст, отдел, зарплату и десяток других полей — хотя на самом деле вам нужны были только имя и фото. Противоположной проблемой является недостаточное количество возвращаемых данных, когда одному виду отображения требуются данные из нескольких ресурсов, что вынуждает отправлять несколько запросов REST и объединять результаты на стороне клиента.

GraphQL решает обе проблемы сразу: один эндпоинт в сочетании с языком запросов, позволяющим клиенту точно указать, какие поля он хочет получить.

# Instead of hitting /employees/123 and getting everything,
# you describe precisely what you need in the request body
query {
  employee(id: "123") {
    name
    photo
  }
}

Ответ содержит только эти два запрошенных поля — ничего лишнего. Нужна ещё зарплата? Просто добавьте её в запрос. Нет необходимости создавать отдельный эндпоинт для этого.

GraphQL поддерживает три вида операций. Запрос считывает данные и выполняет ту же функцию, что и метод GET в REST. Мутация записывает или изменяет данные, заменяя собой комбинацию методов POST, PUT и DELETE. Подписка обеспечивает потоковую передачу данных для непрерывных обновлений и работает примерно так же, как WebSockets.

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

В чём оно уступает: базовые CRUD-сервисы, для которых простые конечные точки REST уже хорошо справляются со своей задачей. GraphQL вносит реальную сложность на стороне сервера, кэширование становится заметно сложнее по сравнению с REST, и это часто бесполезная нагрузка, когда потребности в данных стабильны и чётко определены.

WebSockets: Постоянное соединение

Функции реального времени выявляют фундаментальную слабость REST. Чтобы узнать, пришло ли новое сообщение в чат, клиент на основе REST должен постоянно запрашивать: «Есть ли что-то новое?» снова и снова. Умножьте это на миллион одновременных пользователей — и получите миллион запросов в секунду, при этом подавляющее большинство из них дают ответ «нет», что является чистой тратой ресурсов.

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

GET /chat HTTP/1.1
Upgrade: websocket
Connection: Upgrade

Как только сервер принимает запрос, это HTTP-соединение преобразуется в WebSocket-соединение. С этого момента любая из сторон может отправлять сообщения другой в любое время без необходимости сначала запрашивать разрешение. Канал остается открытым до тех пор, пока одна из сторон намеренно его не закроет.

Соединение WebSocket проходит через четыре различных состояния: Connecting (происходит установление соединения), Open (сообщения передаются в обе стороны), Closing (началась процедура закрытия) и Closed (соединение больше не существует). Попытка отправить данные по уже закрытому соединению приведет к сбою сервера — это частая ошибка у начинающих.

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

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

Webhooks: сервер обращается к вам

И REST, и WebSockets начинаются с клиента: клиент устанавливает соединение, отправляет запрос, а сервер отвечает. Webhooks полностью меняют этот порядок — вместо того чтобы вы запрашивали у сервера обновления, сервер сам связывается с вами в тот момент, когда происходит что-то важное, о чём стоит знать.

Механизм довольно прост. Вы регистрируете URL в какой-либо сторонней службе и указываете, что делать с этим URL: например, «когда платеж будет завершён, отправьте запрос типа POST сюда». Как только платеж действительно проходит, поставщик платежных решений — Razorpay, Stripe или любой другой, который вы используете — автоматически отправляет запрос на ваш конечный пункт. Не требуется цикл опроса или постоянный мониторинг соединения. Вам просто нужно ждать поступления вызова.

# What you give Razorpay in setup:
Webhook URL: https://yourapp.com/webhooks/payment

# What Razorpay sends when payment completes:
POST https://yourapp.com/webhooks/payment
{
  "event": "payment.captured",
  "payload": { "amount": 50000, "order_id": "order_abc" },
  "signature": "sha256_hash_here"
}

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

Когда использовать: для подтверждения оплаты, изменения статуса заказа, в работе CI/CD-пайплайнов (GitHub уведомляет ваш сервер каждый раз, когда поступает новый код), а также в любых процессах, где необходимо реагировать на события, происходящие во внешних системах.

Когда его не следует использовать: в случаях, когда требуется мгновенный ответ в рамках той же сессии общения с пользователем. Webhooks работают с задержкой — они по своей природе асинхронны. Когда пользователь сидит перед экраном и ждет подтверждения прямо сейчас, REST остается более подходящим решением.

gRPC: высокая скорость обмена данными для внутренних сервисов

Большинство крупных приложений состоят не из одного сервера. Например, платформа вроде Zomato использует отдельные сервисы для обработки заказов, платежей, уведомлений и данных о ресторанах, причем эти сервисы вызывают друг друга тысячи раз в секунду. Если весь этот внутренний обмен происходит через REST, придется постоянно сериализовывать и десериализовывать JSON. Читаемость JSON отлично подходит для разработчика, изучающего логи, но при больших объемах данных эта же читаемость сопровождается значительными затратами на парсинг.

gRPC, изначально созданный Google для обработки собственного внутреннего трафика, заменяет JSON на Protocol Buffers (Protobuf) — двоичный формат, который гораздо компактнее и позволяет быстрее кодировать и декодировать данные. Тот же самый пакет данных, который REST передает в виде читаемого текста, gRPC отправляет в виде компактного двоичного блока, который машины обрабатывают намного быстрее.

// You define your data structure once in a .proto file
message OrderRequest {
  string order_id = 1;
  string user_id = 2;
  float amount = 3;
}

Повышение производительности связано не только с форматом данных. gRPC также работает на основе HTTP/2, что позволяет использовать мультиплексацию — тысячи запросов могут передаваться одновременно по одному общему соединению, в отличие от HTTP/1.1, где они обрабатываются по одному. Кроме того, gRPC предлагает четыре различных режима коммуникации: Унарный (один запрос с одним ответом, по структуре аналогичен REST), Стриминг с сервера (один запрос, запускающий поток ответов, удобен для отслеживания заказов в реальном времени), Стриминг с клиента (множество запросов объединяются в один окончательный ответ, полезно для загрузки файла по частям) и Двусторонний стриминг (обе стороны постоянно передают данные друг другу, что подходит для функций реального времени совместной работы).

Когда использовать его: при обмене данными между сервисами внутри собственной инфраструктуры, где важны скорость и строгая типизация. Там, где сервисы обмениваются большими объемами запросов, а парсинг JSON становится значительной нагрузкой.

Когда не использовать его: для API, доступных извне и используемых браузерами или разработчиками снаружи. Бинарная природа Protobuf затрудняет их анализ и отладку, а для работы в браузере требуется дополнительная настройка. Для всех продуктов, предназначенных для конечных пользователей, REST остается более практичным выбором.

SOAP: строгий, многословный, но по-прежнему используемый банками

SOAP (Simple Object Access Protocol) был создан ещё в 1998 году, что делает его старше самого REST. Сегодня большинство разработчиков сталкиваются с ним только при подключении к банковским системам, страховым платформам или крупному корпоративному программному обеспечению — отраслям, которые рано приняли SOAP и у которых так и не появилось веских причин отказаться от него.

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

<!-- Every SOAP message follows this envelope structure -->
<Envelope>
  <Header>
    <Security><!-- authentication goes here --></Security>
  </Header>
  <Body>
    <GetAccountBalance>
      <AccountId>ACC123</AccountId>
    </GetAccountBalance>
  </Body>
</Envelope>

Такая тяжёлая структура существует намеренно. Стандарт WS-Security в SOAP объединяет механизмы аутентификации, цифровых подписей и шифрования в одно сообщение. Для финансовых операций, где любое вмешательство в процесс передачи данных может привести к серьёзным убыткам, такой встроенный уровень защиты оправдывает дополнительную тяжесть сообщений.

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

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

Карта принятия решений

Используйте её в качестве быстрого справочника для выбора подходящего инструмента:

Стандартные веб-приложения или API, предназначенные для работы с общественностью, используют REST. Мобильные приложения, требующие гибких данных, адаптируемых под формат приложения, используют GraphQL. Для общения в реальном времени, многопользовательского взаимодействия или уведомлений в реальном времени применяются WebSockets. Для подтверждения платежей и запуска процессов CI/CD используются Webhooks. Внутренние микросервисы, требующие высокой производительности, используют gRPC. Банковские системы и интеграции с устаревшими корпоративными решениями используют SOAP.

Что вы теперь понимаете

REST по-прежнему остается стандартным выбором. Все остальные паттерны существуют для устранения конкретных недостатков REST: GraphQL используется тогда, когда данные должны отличаться в зависимости от клиента, WebSockets — когда необходимо поддерживать открытую связь в обоих направлениях, Webhooks — когда нужно реагировать на события вместо постоянных запросов к ним, gRPC — когда JSON становится слишком медленным для внутренних сервисных операций, а SOAP — когда требования к корпоративной безопасности не оставляют другого выбора.

В следующий раз, когда вы будете проектировать интеграцию, не начинайте с вопроса о том, как применить REST. Вместо этого спросите, какой паттерн общения действительно соответствует потребностям системы. Именно этот ответ должен определять выбор инструмента, а не привычка.

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