Общие типы API и веб-сервисов

Говоря о "типах" веб-сервисов, необходимо различать следующие термины, так как их легко перепутать:

Такой протокол, как SOAP или XML-RPC, описывает действительный синтаксис API-запросов и ответов.
Архитектурный стиль или парадигма, как REST, устанавливает правила и цели API, но не обязательно должна охватывать точный синтаксис или детали коммуникации.
Языки описания, такие как WADL (для RESTful web services) или WSDL (для веб-служб, основанных на SOAP), описывают API только стандартизированным образом. В них перечислены все API-методы и параметры, а также формат запросов и ответов. Языки описания часто используют язык разметки XML
Такие языки как GraphQL, JSON или XML используются для определения формата и синтаксиса вызовов API (запросов и ответов) или описания API. Это означает, что API, имеющий документацию, написанную на XML, может использовать JSON или простые строки запроса для реальных вызовов API, и не обязательно также использовать XML для этого.

API протокол на примере: SOAP

Simple Object Access Protocol или SOAP - "облегченный протокол, предназначенный для обмена структурированной информацией в децентрализованной, распределенной среде" (https://www.w3.org/TR/soap12-part1), преемник XML-RPC.
Его API-вызовы используют вариант языка разметки XML для стандартизированной коммуникации
SOAP API обычно описываются с помощью WSDL
Концепция инкапсуляции данных определяет сообщения, состоящие из конверта, который содержит заголовок SOAP и тело SOAP

Необработанный запрос (текстовый / xml формат) для вызова SOAP POST:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="http://www.soapui.org/sample/">;
    <soap:Header/>
    <soap:Body>
        <sam:search>
            <searchstring>Alice</searchstring>
        </sam:search>
    </soap:Body>
</soap:Envelope>

После отправки, конечная точка API будет искать лиц, чьё имя совпадает с именем, определённым внутри тэга <searchstring>.
Ответ также XML (результат поиска выделен):

Ответ SOAP соответствует тем же правилам и синтаксису, что и запрос. Но вместо объекта <sam:search> он будет использовать <sam:searchResponse> для обслуживания результата поиска.

Если ничего не было найдено, результат поиска выдаст сообщение об ошибке:

Язык описания на примере: WADL

Язык описания веб-приложений - это стандартизированный метод описания веб-приложений на основе HTTP.
Он был разработан для поддержки моделирования и визуализации приложений, генерации кода, а также настройки клиента и сервера.
WADL основан на XML - так же, как и SOAP.
Файл описания WADL состоит из требуемого корневого элемента " application", элементов " resources" и пары других необязательных элементов:

Также требуется: выделенный атрибут пространства имён xmlns="http://wadl.dev.java.net/2009/02".

Postman позволяет напрямую импортировать действующую WADL и генерировать из нее новую коллекцию. Этот пример взят из официальной спецификации WADL по адресу https://www.w3.org/Submission/wadl/.

Импортировать WADL напрямую:

1. Нажмите кнопку "Import " в верхней части пользовательского интерфейса Postman, а затем либо откройте файл WADL в диалоге " Import File ", либо выберите опцию " Paste Raw Text " для копирования-вставки кода напрямую.
2. При условии, что синтаксис WADL был правильным, Postman сохранит все запросы из документации в новую коллекцию:

Язык на примере: JSON
JSON - аббревиатура от "JavaScript Object Notation". Как следует из названия, каждый кусочек JSON 'кода' на самом деле является действительным javascript объектом. Это имеет много преимуществ:

Он может быть легко конвертирован в другие языки
У него очень мало накладных расходов, JSON-объект состоит только из очень небольшого количества символов - кроме реальной полезной нагрузки (данных, которые вы предоставляете в или из API). Поэтому его читабельность также замечательна - как только вы освоите довольно простой синтаксис: {"имя": "Джон", возраст: 31 год, "город": "Нью-Йорк" }
Весь объект JSON заключен в фигурные скобки.
Отдельные параметры разделены запятыми
Пары "ключ-значение" разделены двоеточиями, как в слове "ключ": "значение"
Текст (строки) должен быть в кавычках: "Нью-Йорк"
Допускаются различные типы данных, например, строки, числа, массивы и другие JSON-объекты (заключенные в фигурные скобки).

Пример:

{"gigs": [
    {"name": "pop concert", "description": "a wonderful evening"},
    {"name": "festival", "description": "a weekend full of fun"}
]}

Не требуется соблюдать интервал или подкладку, но для большей читабельности рекомендуется использовать некоторый отступ и ставить каждый объект в свою линию. Все пробелы белого цвета, не являющиеся частью значения (внутри кавычек), обычно обрезаются и отбрасываются сервером

Давайте посмотрим пример на Postman:

Это тот же самый запрос, что и раньше (поиск лиц по имени), но с JSON на этот раз:

Результатом является также JSON-объект: {" Alice Xiang}"
Убедитесь, что для запроса выбрано правильное Content-Type: application/json.

Если для заданной строки поиска нет корректного результата, вы получите этот ответ -"не найден" :

Другие интересные инструменты и технологии тестирования API

В этом курсе вы научились тестировать веб-сервисы с помощью Postman. Конечно, есть и другие инструменты, о которых вы, по крайней мере, должны были слышать.

SoapUI
SoapUI является тестовым приложением как для API REST, так и для SOAP API. Базовая версия является открытой и бесплатной. Его основное применение заключается в разработке и выполнении автоматизированных тестов, но также может быть использовано для ручного тестирования.

GraphQL
Первоначально разработанный Facebook и для Facebook, GraphQL быстро стал популярным языком для веб-сервисов. Хостингом этой технологии с открытым исходным кодом является некоммерческий Фонд Linux.
Язык имеет свой собственный графический интерфейс GraphQL Schema Definition Language. Он выглядит несколько похожим на JSON. Но помимо того, что он является чистым форматом передачи данных, у него есть свой очень мощный язык запросов и модификаций данных

Swagger UI Еще один проект с открытым исходным кодом, который помогает в предоставлении документации по веб-сервисам.
Он состоит из коллекции активов HTML, Javascript и CSS, и может автоматически генерировать просматриваемую веб-документацию из любого совместимого API.

Вот файлы скриптов, используемые в запросах в этом курсе: https://github.com/MartinRJ/testtraining.