Практика и WSDL 2.0

Стиль document/literal wrapped

Самый совместимый способ оформить SOAP-сервис — document/literal wrapped:

Для каждой операции в схеме объявляется элемент-обёртка запроса с тем же именем, что у операции (CreateOrder), и элемент-обёртка ответа (CreateOrderResponse).
У входного и выходного сообщения ровно по одной части parameters, которая ссылается на обёртку.
Привязка — style="document", use="literal".

Так тело SOAP однозначно показывает, какая операция вызывается, сообщение полностью описано схемой и проверяется валидатором, а генераторы кода (JAX-WS, .NET, gSOAP) создают удобные методы с параметрами. Все примеры в этой документации построены по этому шаблону.

Правила совместимости (WS-I Basic Profile)

Используйте document/literal или rpc/literal, не encoded.
В стиле document у сообщения не больше одной части в теле, и она ссылается на элемент (element), а не на тип.
Указывайте soapAction в soap:operation; значения не должны совпадать у разных операций, если сервер различает их по нему.
Не используйте перегрузку операций (одинаковые имена в одном portType).
Подключайте схемы через xs:import с schemaLocation, а WSDL — через wsdl:import, не смешивая их.

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

Меняйте targetNamespace при несовместимых изменениях (…/orders/v2) и публикуйте новую версию рядом со старой.
Совместимые изменения — новые необязательные элементы в конце последовательности, новые операции — не требуют новой версии, если клиенты не проверяют ответы строгой схемой.
Храните схемы типов в отдельных XSD-файлах: их переиспользуют несколько сервисов, а WSDL остаётся компактным.

WSDL 2.0

WSDL 2.0 — рекомендация W3C 2007 года. Она упрощает и переименовывает конструкции 1.1, но распространена значительно меньше: большинство существующих SOAP-сервисов описаны в WSDL 1.1.

WSDL 1.1	WSDL 2.0
`definitions`	`description`
`portType`	`interface` (с наследованием интерфейсов)
`message` и `part`	Нет: операции ссылаются на элементы схемы напрямую
Четыре вида операций	Шаблоны обмена сообщениями (MEP): `in-only`, `in-out`, `robust-in-only` и др.
`port`	`endpoint`
Привязка HTTP ограничена	Полноценная привязка HTTP, пригодная для описания REST
Пространство имён `http://schemas.xmlsoap.org/wsdl/`	`http://www.w3.org/ns/wsdl`

Для описания REST API сегодня используют OpenAPI — для него в «Помощнике SA» есть отдельный редактор и документация.