Что такое SOAP API? — Q&A Хекслет
2026-02-26 20:17 Diff
https://ru.hexlet.io/qna/glossary/questions/chto-takoe-soap-api

SOAP API

SOAP API — это способ, с помощью которого программы обмениваются сообщениями по сети. Расшифровка — Simple Object Access Protocol («простой протокол доступа к объектам»). Если объяснить простыми словами, SOAP — это правила для обмена структурированными XML-сообщениями между приложениями через интернет или корпоративные сети.

SOAP появился еще в конце 1990-х годов и стал основой множества корпоративных интеграций. Несмотря на рост популярности REST и GraphQL, simple object access protocol до сих пор активно используется там, где важны строгие контракты, безопасность, надёжность — в банках, телекомах, госуслугах, крупных корпоративных системах.

Где используется сегодня

SOAP-веб-сервисы чаще всего встречаются:

  • в банковских API (платёжные шлюзы, валютные курсы, отчётность);

  • у телеком-операторов (биллинговые системы, роуминг, CRM);

  • в государственных сервисах (Госуслуги, ЕГАИС, СМЭВ);

  • в ERP, интеграционных шинах (SAP, Oracle, 1С, BizTalk).

Сервисы удобны там, где нужно не просто «передать данные», а строго следовать описанному контракту (WSDL) и обеспечивать надежность, безопасность сообщений.

Архитектура SOAP и стек WS-*

SOAP — это не просто XML, а часть большого WS-стека (Web Services). Основные компоненты:

  • SOAP — формат сообщений, правил обмена;

  • WSDL — контракт, описывающий, какие методы / данные поддерживает сервис;

  • WS-Addressing — задаёт маршрутизацию сообщений;

  • WS-Security — обеспечивает подписи, шифрование, аутентификацию;

  • WS-ReliableMessaging — отвечает за гарантированную доставку;

  • WS-AtomicTransaction — координирует распределенные транзакции.

Таким образом, SOAP — это фундамент, на котором строится целый стек надежных веб-сервисов.

Из чего состоит сообщение SOAP

SOAP-сообщение всегда представляет собой XML-документ со структурой:

Основные элементы:

  • Envelope — оболочка всего сообщения.

  • Header — метаданные (авторизация, маршрутизация, подписи).

  • Body — основное содержимое (запрос или ответ).

  • Fault — описание ошибки.

SOAP 1.1 vs SOAP 1.2

  • В SOAP 1.2 используется атрибут soap:role вместо actor.

  • mustUnderstand — булев (true/false), а не числовой (1/0).

  • Кодировки, пространства имён отличаются, поэтому версии несовместимы.

  • SOAP 1.2 — сам по себе не гарантирует надёжность; она обеспечивается WS-ReliableMessaging.

Примеры XML для запроса и ответа

Пример запроса:

Пример ответа:

Ошибка (Fault):

Формат данных и вложения

Основной формат данных в SOAP — XML, но возможны вложения:

  • MTOM/XOP — передача бинарных файлов (например, PDF, изображений) в виде вложений, а не base64 внутри XML.

  • base64Binary — альтернатива, если MTOM не поддерживается.

Это делает SOAP гибким для сложных интеграций, где нужны документы, медиафайлы.

Транспорт и HTTP SOAP

Чаще всего SOAP работает поверх HTTP/HTTPS.

Типичные заголовки:

SOAP 1.1

POST /service HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "GetBalance"

SOAP 1.2

POST /service HTTP/1.1 Content-Type: application/soap+xml; charset=utf-8; action="GetBalance"

При ошибках сервис может вернуть HTTP 500 (Fault) или 200 (успешный ответ).

Кроме HTTP, возможны альтернативные транспорты — SMTP, JMS, MQ, другие.

Стили и кодирование

SOAP поддерживает два стиля:

  • RPC (Remote Procedure Call) — имитирует вызов функции.

  • Document — передаёт документы с данными (рекомендуется).

По способу кодирования:

  • encoded — старый формат (SOAP encoding);

  • literal — предпочтительный, совместимый с WS-I Basic Profile.

Контракт: WSDL «для чайников»

Файл WSDL (Web Services Description Language) — это XML-контракт, описывающий:

  • types — используемые структуры данных (XSD);

  • message — входные / выходные сообщения;

  • portType — операции (методы);

  • binding — способ передачи (SOAP 1.1/1.2);

  • service — адреса (endpoint’ы).

Клиент по WSDL может автоматически сгенерировать код:

  • Java: wsimport;

  • .NET: svcutil;

  • Python: zeep.

Синхронный или асинхронный

SOAP-вызовы могут быть:

  • синхронными (request/response);

  • асинхронными — с колбэками или polling (опросом).

Для связывания запросов / ответов используют correlation IDs.

Обработка ошибок

В SOAP 1.1 ошибка описывается через <soap:Fault>, а в 1.2 — структура изменена:

Ошибки обычно маппятся на HTTP 500 (внутренняя ошибка) или 400 (некорректный запрос).

Безопасность и надежность

SOAP сам по себе не шифрует, не подписывает данные — это делают расширения:

  • WS-Security — подпись, шифрование, токены:

    • UsernameToken, X.509, SAML;

  • WS-ReliableMessaging — гарантирует доставку, порядок сообщений;

  • WS-Policy — описывает требования к безопасности;

  • TLS/HTTPS — защищает транспорт.

Практика и инструменты

Тестирование:

  • SoapUI — популярный инструмент для создания / отладки запросов;

  • Postman — тоже поддерживает SOAP (через XML-тело);

  • cURL — можно отправить вручную:

curl -X POST -H "Content-Type: text/xml" -d @request.xml https://example.org/service

Генерация клиента:

  • Java: wsimport;

  • .NET: svcutil;

  • Python: zeep.

Сравнение SOAP и REST

Выбирают SOAP, если важны безопасность, транзакции, строгие контракты.

REST — когда нужна простота, скорость.

Частые проблемы и отладка

  • Ошибки в namespace (xmlns) — частая причина «Invalid SOAP message».

  • Несовпадение типов XSD при сериализации.

  • Большие вложения → включают MTOM.

  • Проблемы с таймаутами, SSL-сертификатами.

FAQ по ключам

  • SOAP-запрос — это XML-сообщение, отправляемое клиентом на сервер.

  • Envelope SOAP — внешняя оболочка сообщения.

  • SOAP-метод — операция, определенная в WSDL.

  • Формат данных — XML, с поддержкой MTOM/XOP для бинарных вложений.

  • HTTP SOAP — наиболее распространенный транспортный протокол.

Глоссарий

  • Envelope — контейнер SOAP-сообщения.

  • Header — метаданные, служебная информация.

  • Body — данные запроса или ответа.

  • Fault — структура ошибки.

  • WSDL — описание контракта веб-сервиса.

  • binding — способ передачи данных.

  • portType — набор операций сервиса.

  • MTOM/XOP — механизмы передачи бинарных вложений.

Полезные материалы и спецификации