SOAP API

t.me/qa_chillout

Что такое SOAP API

SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам) — протокол обмена структурированными сообщениями в распределенной вычислительной среде. Протокол используется для обмена произвольными сообщениями в формате XML.

SOAP используется с различными протоколами, таким как SMTP, FTP, HTTP, HTTPS. Чаще всего — с HTTP как с наиболее универсальным: его поддерживают все браузеры и серверы.

SOAP API — это веб-сервис, использующий протокол SOAP для обмена сообщениями между серверами и клиентами. При этом сообщения должны быть написаны на языке XML в соответствии со строгими стандартами, иначе сервер вернет ошибку.

Основные определения

XML

XML (или Extensible Markup Language) — это простой, очень гибкий текстовый формат, устанавливающий набор правил для структурирования сообщений. XML создали для удобного хранения и передачи данных. У XML есть ряд преимуществ, которые позволяют успешно справляться с этой задачей. Например, его может прочитать абсолютно любой желающий:

<?xml version="1.0" encoding="UTF-8"?>
<book>
   <title>iPhone 12 Pro</title>
   <memory>512</memory>
   <price>100 000</price>
</book>

А также при передаче данных от клиента на сервер и наоборот нет проблем с совместимостью данных.

XSD

XSD (XML Schema Definition) — язык описания структуры XML-документа. Он используется для определения правил, которым должен подчиняться документ и был разработан так, чтобы его можно было использовать в создании программного обеспечения для обработки XML-документов. Файл, содержащий XML Schema, обычно имеет расширение «.xsd» (XML Schema definition). Перед тестированием SOAP первым делом необходимо проверить документацию XSD, так как там довольно часто встречаются ошибки (например, некорректно заданы ограничения).

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

В следующем примере определяется элемент «age» с ограничением. В этом элементе предполагается указывать возраст человека, а возраст человека, как известно, не может быть меньше 0 и больше 125:

<xs:element name="age">
   <xs:simpleType>
      <xs:restriction base="xs:integer">
         <xs:minInclusive value="0"/>
         <xs:maxInclusive value="125"/>
      </xs:restriction>
   </xs:simpleType>
</xs:element>

В следующем примере определяется другой элемент «password» с ограничением. Длина его значения должна быть минимум 5 и максимум 8 символов:

<xs:element name="password">
   <xs:simpleType>
      <xs:restriction base="xs:string">
         <xs:minLength value="5"/>
         <xs:maxLength value="8"/>
      </xs:restriction>
   </xs:simpleType>
</xs:element>

Как уже было сказано выше, схема подключается и находится в отдельном файле:

<?xml version="1.0"?>
<note xmlns="http://mysite.ru"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://mysite.ru note.xsd">
   <title>iPhone 12 Pro</title>
   <memory>512</memory>
   <price>100 000</price>
</note>

Фрагмент xmlns:xs="http://www.w3.org/2001/XMLSchema" указывает на то, что используемые в схеме элементы и типы данных относятся к пространству имен "http://www.w3.org/2001/XMLSchema". Также здесь указывается, что элементы и типы данных, относящиеся к пространству имен "http://www.w3.org/2001/XMLSchema", должны иметь префикс xs:

Фрагмент targetNamespace="http://msiter.ru" указывает на то, что определяемые этой схемой элементы (note, to, from, heading, body) относятся к пространству имен "http://msiter.ru".

Фрагмент xmlns="http://mysite.ru" указывает на то, что пространством имен по умолчанию является "http://mysite.ru".

XML схемы предназначены для определения допустимых строительных блоков XML документа. XML схема определяет:

элементы, которые могут появляться в XML документе
атрибуты, которые могут появляться в XML документе
какие элементы являются дочерними
порядок дочерних элементов
количество дочерних элементов
пустой ли элемент или может содержать текст
типы данных элементов и атрибутов
фиксированные значения и значения по умолчанию элементов и атрибутов

Комментарии могут появляться в любом месте документа за пределами другой разметки, кроме того, они могут появляться в объявлении типа документа в местах, разрешенных грамматикой. Они не являются частью символьных данных документа.

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

Пример неправильных комментариев:

Таблица ограничения для типов данных:

WSDL

Web Services Description Language (WSDL) – это язык на основе XML, который используется для описания веб-сервисов. Эта аббревиатура также используется для любого конкретного WSDL-описания сервиса. Описание представляет собой текстовый WSDL-файл, который содержит описание того, как можно вызвать службу, какие параметры она ожидает и в каком формате она возвращает данные.

Документ WSDL использует следующие элементы в определении сетевых служб:

Определение – корневой элемент всех документов WSDL. Он определяет имя веб-службы, объявляет несколько пространств имен, используемых в оставшейся части документа, и содержит все элементы службы, описанные здесь.
Типы данных – типы данных, которые будут использоваться в сообщениях, представлены в форме схем XML.
Сообщение – это абстрактное определение данных в форме сообщения, представленного либо в виде всего документа, либо в качестве аргументов, которые должны быть сопоставлены с вызовом метода.
Операция – это абстрактное определение операции для сообщения, например, присвоение имени методу, очереди сообщений или бизнес-процессу, которое примет и обработает сообщение.
Тип порта – это абстрактный набор операций, сопоставленный с одной или несколькими конечными точками, определяющий набор операций для привязки; коллекция операций, как она абстрактна, может быть сопоставлена с несколькими транспортными средствами через различные привязки.
Связывание – это конкретный протокол и форматы данных для операций и сообщений, определенных для определенного типа порта.
Порт – это сочетание привязки и сетевого адреса, обеспечивающее целевой адрес службы связи.
Сервис – это набор связанных конечных точек, охватывающий определения сервиса в файле; службы сопоставляют привязку с портом и включают любые определения расширяемости.

Структура SOAP-сообщения

Корректное SOAP-сообщение состоит из нескольких структурных элементов: Envelope, Header, Body и Fault.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
     <getProductDetails xmlns="http://warehouse.example.com/ws">
       <productID>8239</productID>
     </getProductDetails>
   </soap:Body>
</soap:Envelope>

В самой первой строке объявляется XML.

<?xml version="1.0" encoding="utf-8"?>

Объявление XML указывает версию языка, на которой написан документ. Поскольку интерпретация содержимого документа зависит от версии языка, то Спецификация предписывает начинать документ с объявления XML. В первой (1.0) версии языка использование объявления не было обязательным, в последующих версиях оно обязательно. Таким образом, версия языка определяется из объявления, и если объявление отсутствует, то принимается версия 1.0.

Кроме версии XML объявление может также содержать информацию о кодировке документа и «оставаться ли документу со своим собственным DTD (DTD («document type definition») — позволяет определить список разрешенных элементов для какой-то сущности в XML-файле.), или с подключенным».

Envelope («конверт»). Это корневой элемент. Определяет XML-документ как сообщение SOAP с помощью пространства имен xmlns:soap=»http://www.w3.org/2003/05/soap-envelope/». Если в определении будет указан другой адрес, сервер вернет ошибку.

Header («заголовок»). Включает в себя атрибуты сообщения, связанные с конкретным приложением (аутентификация, проведение платежей и так далее). В заголовке могут использоваться три атрибута, которые указывают, как принимающая сторона должна обрабатывать сообщение, — mustUnderstand, actor и encodingStyle. Значение mustUnderstand — 1 или 0 — говорит принимающему приложению о том, следует ли распознавать заголовок в обязательном или опциональном порядке. Атрибут actor задает конкретную конечную точку для сообщения. Атрибут encodingStyle устанавливает специфическую кодировку для элемента. По умолчанию SOAP-сообщение не имеет определенной кодировки.

Body («тело»). Сообщение, которое передает веб-приложение. Может содержать запрос к серверу или ответ от него.

Пример запроса к сервису Яндекс.Спеллер:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:spel="http://speller.yandex.net/services/spellservice">
   <soap:Header/>
   <soap:Body>
      <spel:CheckTextRequest lang="ru" options="0" format="">
         <spel:text>кылбаса</spel:text>
      </spel:CheckTextRequest>
   </soap:Body>
</soap:Envelope>

Пример ответа от сервиса Яндекс.Спеллер:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <CheckTextResponse xmlns="http://speller.yandex.net/services/spellservice">
         <SpellResult>
            <error code="1" pos="0" row="0" col="0" len="7">
               <word>кылбаса</word>
               <s>колбаса</s>
            </error>
         </SpellResult>
      </CheckTextResponse>
   </soap:Body>
</soap:Envelope>

В чем недостатки SOAP

К недостаткам SOAP можно отнести:

использование SOAP для передачи сообщений увеличивает их объем и снижает скорость обработки;
только один поддерживаемый формат — XML;
схема работы по принципу «один запрос — один ответ».

Полезные ссылки

Обсудить статью, узнать больше можно в телеграм канале «Тестировщики нужны».