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 документе
- какие элементы являются дочерними
- порядок дочерних элементов
- количество дочерних элементов
- пустой ли элемент или может содержать текст
- типы данных элементов и атрибутов
- фиксированные значения и значения по умолчанию элементов и атрибутов
Комментарии могут появляться в любом месте документа за пределами другой разметки, кроме того, они могут появляться в объявлении типа документа в местах, разрешенных грамматикой. Они не являются частью символьных данных документа.
Пример комментариев:
<!-- объявления для <head> и <body> -->
Пример неправильных комментариев:
<!-- объявления для <head> и <body> --->
Таблица ограничения для типов данных:
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;
- схема работы по принципу «один запрос — один ответ».
Полезные ссылки
- https://blog.skillfactory.ru/glossary/soap-api/
- https://www.w3.org/TR/2008/REC-xml-20081126/
- https://www.w3.org/TR/2001/NOTE-wsdl-20010315
- https://coderlessons.com/tutorials/xml-tekhnologii/uznaite-wsdl/wsdl-kratkoe-rukovodstvo
Обсудить статью, узнать больше можно в телеграм канале «Тестировщики нужны».