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-документ со структурой:

<soap:Envelope
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
	<soap:Header>
		<authToken soap:mustUnderstand="true">abc123</authToken>
	</soap:Header>
	<soap:Body>
		<m:GetUser
			xmlns:m="http://example.org/user">
			<m:id>1001</m:id>
		</m:GetUser>
	</soap:Body>
</soap:Envelope>

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

• 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 для запроса и ответа

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

<soap:Envelope
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<m:GetBalance
			xmlns:m="http://example.org/account">
			<m:accountId>12345</m:accountId>
		</m:GetBalance>
	</soap:Body>
</soap:Envelope>

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

<soap:Envelope
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<m:GetBalanceResponse
			xmlns:m="http://example.org/account">
			<m:balance>1000.50</m:balance>
		</m:GetBalanceResponse>
	</soap:Body>
</soap:Envelope>

Ошибка (Fault):

<soap:Envelope
	xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<soap:Fault>
			<faultcode>soap:Client</faultcode>
			<faultstring>Invalid account ID</faultstring>
			<detail>
				<errorCode>4001</errorCode>
			</detail>
		</soap:Fault>
	</soap:Body>
</soap:Envelope>

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

Основной формат данных в 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 — структура изменена:

<soap:Fault>
	<soap:Code>
		<soap:Value>soap:Sender</soap:Value>
	</soap:Code>
	<soap:Reason>
		<soap:Text xml:lang="en">Invalid request</soap:Text>
	</soap:Reason>
</soap:Fault>

Ошибки обычно маппятся на 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 — механизмы передачи бинарных вложений.

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

• SOAP 1.1 Specification (W3C)

• SOAP 1.2 Part 1: Messaging Framework

• WSDL 1.1/2.0 Specifications

• WS-Security Specification

• WS-ReliableMessaging

• Обзор SOAP на Habr

SOAP (Simple Object Access Protocol) API - это протокол обмена данными между различными системами и приложениями. SOAP используется для обмена сообщениями между двумя устройствами, которые могут находиться на разных платформах и использовать разные языки программирования. SOAP API позволяет разработчикам создавать веб-сервисы, которые могут быть доступны для других приложений и устройств.