Шаблон: спецификация SOAP API

Спецификация SOAP API — артефакт системного аналитика, который фиксирует контракт веб-сервиса: бизнес-назначение операций, технический контракт (WSDL/XSD), транспорт, безопасность, ошибки и трассировку к SRS/BRD. В отличие от REST (10.01.04 Шаблон спецификации REST API), центр тяжести — операции и типизированные сообщения (конверт SOAP — envelope, заголовки — headers, тело — body), а не ресурсы и HTTP-глаголы. Документ дополняет или ссылается на машиночитаемый WSDL, но не заменяет его: вы добавляете семантику полей, бизнес-правила, NFR и сценарии, которых в WSDL нет. Теория протокола — в 07.02 Принципы работы HTTP, REST, SOAP.

Шаблон ориентирован на WSDL 1.1 (типичный legacy/enterprise-контур). WSDL 2.0 и смешанные контуры допустимы — явно укажите версию в §3.3 и заполняйте поля по таблице соответствия 1.1 ↔ 2.0; детали нотации — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf).

1. Назначение

Спецификацию SOAP API пишет системный аналитик (или аналитик с поддержкой интеграционного архитектора); её читают разработка backend, интеграторы, QA, security и команды потребителей (внутренние и внешние).

Шаблон закрывает четыре задачи:

• Контракт операций — каталог операций (operation) с input/output/fault-сообщениями, binding (document/literal, SOAP 1.1/1.2) и endpoint/destination по средам; одна спека = один веб-сервис или логический порт.
• Семантика сообщений — описание полей XSD сверх типов: бизнес-смысл, обязательность, правила валидации «между полями», примеры XML; без этого codegen и интеграции расходятся в интерпретации.
• Мост к требованиям — трассировка Operation ID → SRS/BRD → user story/use case → тест-кейсы; WSDL сам по себе не передаёт «зачем» операция.
• Управление контрактом (governance) — правило приоритета при расхождении WSDL и текста, политика версионирования, deprecated-операции, retry/fault-поведение для эксплуатации.

WSDL/XSD — machine-readable API spec; markdown/PDF по этому шаблону — contract + semantics + governance. Правило приоритета фиксируется в §3.1.

2. Когда использовать

Подходит, если:

• интегрируете legacy-систему, ESB, банковский/государственный контур, где контракт задан WSDL/XSD;
• проектируете новый SOAP-сервис или меняете существующий (новые операции, breaking change в XSD);
• потребителю нужен человекочитаемый контракт с бизнес-описанием, fault-матрицей и NFR — WSDL недостаточен;
• сервис вызывается синхронно (request-response), one-way или async callback через SOAP over HTTP и/или JMS;
• параллельно с REST-фасадом нужно явно указать «источник истины» контракта и правила маппинга.

Не подходит или требует дополнения, если:

• контракт полностью описан OpenAPI/REST без SOAP-binding — используйте 10.01.04 Шаблон спецификации REST API;
• взаимодействие event-driven через Kafka/RabbitMQ без SOAP-транспорта — 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ) / 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ);
• выбор SOAP vs REST, document/literal wrapped vs bare, политика версионирования — решение в 10.01.13 Шаблон архитектурного решения (ADR); в спеке — следствия для endpoint и namespace;
• latency, rate limits, аудит, MTOM — полный текст в 10.01.12 Шаблон нефункциональных требований (NFR); в спеке — ссылки и параметры, от которых зависит интеграция;
• нужен только обзор нотации SOAP/WSDL — см. 07.02 Принципы работы HTTP, REST, SOAP, 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) и 07.03 Основы XML, JSON, YAML, а не этот шаблон.

Входные условия: границы сервиса и потребители согласованы (03.01.04 Интерфейсы и интеграционные взаимодействия), функциональные требования описаны в SRS/stories/UC, термины домена унифицированы (10.01.14 Шаблон глоссария и словаря данных).

Серия с REST: структура §3 сознательно зеркалит 10.01.04 Шаблон спецификации REST API (метаданные, назначение, NFR по ссылке, трассировка, workflow). Отличия SOAP-шаблона — операции и WSDL/XSD, JMS-транспорт, async callback, fault-матрица и политика HTTP 200 + business error в body.

3. Структура документа

Скопируйте блок в Confluence, Git (markdown + WSDL/XSD в репозитории) или RM-инструмент. Поля с пометкой обяз. нужны для sign-off; остальные — по контексту. Полные XSD выносите в приложение; в теле — таблицы ключевых полей.

Минимальный контур — для внутреннего сервиса с ≤3 операциями, только HTTP, без JMS и callback достаточно §3.1, 3.2, 3.5, 3.6, 3.8, 3.9, 3.12; остальные подразделы пометьте «N/A». Полный контур — enterprise, JMS, callback, shared XSD, MTOM.

Контрактные проверки до кода — см. 02.04.01 Верификация и валидация (V&V) и 08.03 Тестирование требований (статическое тестирование).

3.1. Метаданные

3.2. Назначение сервиса

3.3. Обзор контракта

Соответствие полей WSDL 1.1 ↔ 2.0 (§3.5–3.6 и fault-матрица):

3.4. Среды, endpoints и транспорт

Заполните подразделы по фактическим binding из WSDL: HTTP, JMS или оба. Пустые подразделы пометьте «не используется».

3.4.1. Async callback (если модель из §3.2 включает callback)

Обязательно, если provider отвечает асинхронным вызовом на endpoint consumer.

3.4.2. One-way без callback (fire-and-forget)

Обязательно, если в §3.2 указан one-way без §3.4.1.

3.5. Каталог операций

Сводная таблица + детализация на каждую операцию (отдельный подраздел 3.6).

3.6. Сообщения (на операцию)

Для каждой операции из каталога — отдельный блок.

3.7. SOAP Headers

3.8. Ошибки и faults

Разделяйте SOAP Fault (транспорт/контрактный сбой) и бизнес-ошибку в body (прикладной код в response). Формат Fault зависит от версии SOAP из §3.3: SOAP 1.2 — Code/Subcode; SOAP 1.1 — faultcode (QName), faultstring, detail (без subcode).

3.9. Безопасность

3.10. Нефункциональные требования

3.11. Зависимости

3.12. Тестирование и приёмка

3.13. Открытые вопросы, допущения, история

3.14. Приложения

3.15. Чеклист качества перед sign-off

Рецензия спеки — 08.04 Рецензирование и инспекции (техники Фейгана).

• У каждой операции есть Operation ID, trace к SRS/story и описание в WSDL.
• Описаны input, output и fault-ветки; не только happy path; для one-way без response — явно N/A + §3.4.2.
• Каждый WSDL fault из §3.6 имеет строку в матрице §3.8 с корректным форматом SOAP 1.1 или 1.2.
• SOAP Fault и бизнес-ошибки в body разведены по разным строкам матрицы.
• Политика HTTP-кодов (§3.4, §3.8) согласована с QA и REST-фасадом (если есть); business-ответы не путают с transport fault.
• Указаны версия SOAP, WSDL, binding, charset; endpoints (HTTP) и/или JMS destinations по всем средам.
• Для async callback заполнен §3.4.1; для one-way без callback — §3.4.2.
• Идемпотентность: ключ и семантика повтора (duplicate vs same result) заданы для каждой операции, где применимо.
• Внешние XSD import/include перечислены; governance shared XSD (§3.3) согласован с владельцами.
• При WSDL 2.0 поля §3.5–3.6 заполнены по таблице соответствия §3.3.
• Deprecated operations и migration window отражены в §3.3/§3.5, если есть sunset.
• Семантика полей заполнена — не только xs:string.
• Правило версионирования и breaking change согласованы с ADR.
• Security для prod описана явно, не отсылкой «как в WSDL».
• Таймауты и retry задокументированы для sync-, callback- и one-way-вызовов.
• MTOM и лимиты размера сообщения согласованы между §3.4 и §3.5.
• Корреляция (message id, business id, JMS correlation) согласована с Consumer/Producer при шинной интеграции.
• WSDL/XSD в репозитории совпадает с утверждённой версией документа.
• Минимум sign-off §3.12 выполнен (ручной SoapUI или CI — как зафиксировано).
• Трассировка к 10.01.15 Шаблон матрицы трассировки и тест-кейсам заполнена.

4. Пример заполнения

Сокращённый фрагмент для сервиса PaymentVerificationService (корпоративный шлюз, данные условны).

Метаданные: SOAP-PAY-v3 · PaymentVerificationService · namespace http://corp.example/payment/v3 · Approved · v3.2, 2026-03-10 · WSDL: git@repo/payment-wsdl@v3.2.1 (WSDL 1.1) · Upstream: SRS-REQ-112, ADR-018 (SOAP 1.2, document/literal wrapped) · NFR: NFR-INT-004, NFR-SEC-002 · REST-фасад: API-PAY-REST-v1 (10.01.04 Шаблон спецификации REST API; read-only статус; источник истины — SOAP для write-операций; HTTP-коды business error согласованы) · БД: N/A · Producer/Consumer: N/A · Приоритет: WSDL — типы/binding; документ — семантика и business-коды.

Назначение. Синхронная проверка платёжного поручения перед проведением в АБС. Потребители: order-service, treasury-portal. Sync request-response, SLA-critical. Async callback не используется (§3.4.1 — N/A). One-way не используется (§3.4.2 — N/A).

Обзор контракта. WSDL 1.1, SOAP 1.2, document/literal wrapped, WS-I Basic Profile 1.1. Imported XSD: common-types-v2.xsd (commit abc123, owner platform-team). Governance shared XSD: breaking change в common-types — отдельный релиз с рассылкой всем сервисам-import; bump endpoint сервиса — только для breaking в namespace сервиса. Обратная совместимость: additive — новые optional-элементы в v3; breaking — новый endpoint /payment/v4. Deprecated: LegacyVerify — sunset 2026-12-01, миграция на VerifyPayment.

Транспорт и endpoints. Только HTTP. Политика HTTP: HTTP 200, если envelope валиден; business REJECTED — в body; SOAP Fault — HTTP 500/503 по матрице.

Каталог операций (фрагмент):

OP-PAY-001 — VerifyPayment (фрагмент сообщений):

Request root: VerifyPaymentRequest (type tns:VerifyPaymentRequestType).

Response root: VerifyPaymentResponse. Поле resultCode: OK | REJECTED | PENDING_REVIEW — бизнес-результат, не SOAP Fault.

WSDL fault InvalidAccountFault → матрица: soap:Sender + subcode InvalidAccount.

Минимальный request:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:tns="http://corp.example/payment/v3">
  <soap:Body>
    <tns:VerifyPaymentRequest>
      <tns:paymentRef>a1b2c3d4-e5f6-7890-abcd-ef1234567890</tns:paymentRef>
      <tns:amount>15000.00</tns:amount>
      <tns:currency>RUB</tns:currency>
      <tns:payerAccount>40702810123456789012</tns:payerAccount>
    </tns:VerifyPaymentRequest>
  </soap:Body>
</soap:Envelope>

Response с business-кодом (HTTP 200):

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:tns="http://corp.example/payment/v3">
  <soap:Body>
    <tns:VerifyPaymentResponse>
      <tns:resultCode>REJECTED</tns:resultCode>
      <tns:resultCodeDetail>LIMIT_EXCEEDED</tns:resultCodeDetail>
      <tns:paymentRef>a1b2c3d4-e5f6-7890-abcd-ef1234567890</tns:paymentRef>
    </tns:VerifyPaymentResponse>
  </soap:Body>
</soap:Envelope>

SOAP Fault (SOAP 1.2, HTTP 500) — InvalidAccountFault:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <soap:Fault>
      <soap:Code>
        <soap:Value>soap:Sender</soap:Value>
        <soap:Subcode>
          <soap:Value>tns:InvalidAccount</soap:Value>
        </soap:Subcode>
      </soap:Code>
      <soap:Reason>
        <soap:Text xml:lang="ru">Неверный формат расчётного счёта</soap:Text>
      </soap:Reason>
      <soap:Detail>
        <tns:InvalidAccountDetail xmlns:tns="http://corp.example/payment/v3">
          <tns:field>payerAccount</tns:field>
        </tns:InvalidAccountDetail>
      </soap:Detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Для SOAP 1.1 тот же fault выглядел бы иначе: faultcode (QName, напр. soap:Client), faultstring, detail — без Subcode; формат задаётся в §3.3.

Ошибки (фрагмент матрицы):

Headers. WS-Addressing: MessageID (UUID v4) — генерирует consumer; RelatesTo — только в callback-сценариях (§3.4.1 N/A).

Безопасность. Prod: mTLS + WS-Security UsernameToken в header; роль PAYMENT_INITIATOR для VerifyPayment (10.01.11 Шаблон ролевой модели). Поле payerAccount — маскировать в логах (407028******9012).

NFR. Read timeout 15 s prod; retry только на DownstreamTimeout и HTTP 503 (10.01.12 Шаблон нефункциональных требований (NFR) NFR-INT-004).

Sign-off. Минимум: ручной SoapUI — TC-PAY-001..005 по операции VerifyPayment (OK, REJECTED, InvalidAccount, timeout). CI — не блокирует sign-off v3.2.

Трассировка: US-0312 → OP-PAY-001 → TC-PAY-001..005 → WSDL tag v3.2.1.

5. Связанные артефакты

Структура намеренно параллельна 10.01.04 Шаблон спецификации REST API; ниже — входы/выходы именно SOAP-спеки.

На входе (upstream)

На выходе (downstream)

Типичный порядок работы аналитика

1. Выделить операции из SRS/UC/stories → черновой каталог с Operation ID и trace.
2. Согласовать с архитектором WSDL: portType/interface, messages, binding, namespace, imports XSD.
3. Детализировать сообщения: таблицы полей, бизнес-правила, примеры XML, fault-матрица с mapping WSDL fault → код; для one-way — §3.4.2.
4. Зафиксировать транспорт (HTTP/JMS), callback при необходимости, security, NFR (timeout/retry) — параллельно с 10.01.12 Шаблон нефункциональных требований (NFR).
5. Review с dev, интеграторами, security (08.04 Рецензирование и инспекции (техники Фейгена)); опубликовать WSDL/XSD в репозитории с tag.
6. При изменении XSD — impact analysis на consumers (02.05.02 Управление изменениями (Change Control Board) при формальном процессе); для shared XSD — отдельное согласование владельца схемы.

6. Связи с другими разделами базы

Теория и контекст, не дублирующие §5:

• SOAP vs REST, операционная модель — 07.02 Принципы работы HTTP, REST, SOAP
• Сравнение с REST и gRPC (выбор стека) — 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL)
• WSDL/XSD как контрактные спецификации — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)
• XML, XSD, структура сообщений — 07.03 Основы XML, JSON, YAML
• Диаграмма последовательности для ключевых вызовов — 03.02.03 Диаграмма последовательности (Sequence Diagram)
• Чеклист перед стартом разработки — 10.04 Чеклист аналитика перед стартом разработки

7. Источники и дополнительные материалы

URL в этом блоке взяты из отчёта исследования; перед публикацией имеет смысл перепроверить актуальность вручную (в т.ч. статус WS-I и зеркала OASIS).

Книги и стандарты

• W3C — SOAP 1.1 (Note) — https://www.w3.org/TR/soap/
• W3C — SOAP Version 1.2 Part 1: Messaging Framework (Recommendation) — https://www.w3.org/TR/soap12-part1/
• W3C — SOAP Version 1.2 Part 2: Adjuncts (Recommendation) — https://www.w3.org/TR/soap12-part2/
• W3C — Web Services Description Language (WSDL) 1.1 (Note) — https://www.w3.org/TR/wsdl11
• W3C — Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language (Recommendation) — https://www.w3.org/TR/wsdl20/
• W3C — XML Schema Part 0: Primer — https://www.w3.org/TR/xmlschema-0/
• W3C — Web Services Addressing 1.0 - Core (Recommendation) — https://www.w3.org/TR/ws-addr-core/
• W3C — Web Services Addressing 1.0 - SOAP Binding (Recommendation) — https://www.w3.org/TR/ws-addr-soap/
• W3C — Web Services Policy 1.5 - Framework (Recommendation) — https://www.w3.org/TR/ws-policy/
• OASIS — Web Services Security: SOAP Message Security 1.1 (Standard) — https://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-errata-SOAPMessageSecurity.pdf
• WS-I — Basic Profile 1.1 (interop для SOAP/WSDL) — https://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html

Статьи и практики

• Microsoft — Working with WSDL (WCF documentation) — https://learn.microsoft.com/en-us/dotnet/framework/wcf/feature-details/working-with-wsdl
• Microsoft — Using the XmlSerializer (document/literal, сериализация сообщений) — https://learn.microsoft.com/en-us/dotnet/framework/wcf/feature-details/using-the-xml-serializer