Тестирование api

Четыре типа параметров

REST API обладают 4 типами параметров:

Параметры заголовка: параметры, включенные в заголовок запроса, обычно относятся к авторизации.
Параметры path: Параметры в пределах path конечной точки перед строкой запроса, отделяются знаком . Обычно эти параметры выделяются фигурными скобками.
Параметры строки запроса: Параметры в строке запроса конечной точки, располагаются после знака .
Параметры тела запроса: Параметры, включенные в тело запроса. Обычно в формате JSON.

Tip: Термины для каждого из этих типов параметров взяты из спецификации OpenAPI, которая определяет формальную спецификацию, которая включает описания каждого типа параметра (см. Шаг 4 Объект ). Использование терминологии промышленного стандарта поможет разработать словарь элементов API для их описания.

Тенденции API

Повсеместное распространение Интернета, более широкое использование облачных вычислений и переход от монолитных приложений к микросервисам – все это способствовало широкому распространению API.

REST и Web

Веб-API можно вызывать через любой язык программирования, но также можно получить доступ к веб-страницам, созданным в HTML или инструментах генератора приложений. Возросшая роль Интернета и облака в нашей жизни и деловой активности значительно расширила использование API-интерфейсов и использование простых инструментов программирования или даже отказа от программирования для доступа к API.

И REST, и SOAP могут вызывать облачные сервисы, подключаться к ним и взаимодействовать с ними, но REST все чаще предпочтительнее для веб-API, поскольку он использует меньшую пропускную способность и предлагает больше возможностей для языков программирования, таких как JavaScript или Python. Крупные веб-сайты, такие как Amazon, Google, LinkedIn и Twitter, используют RESTful API.

API и облако

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

Эти облачные возможности сместили фокус API-интерфейсов с простых моделей, ориентированных на RPC-программиста, на веб-модели RESTful и даже на то, что называется «функциональным программированием» или «лямбда-моделями» сервисов, которые можно мгновенно масштабировать по мере необходимости в облако.

API как сервисы

Тенденция рассматривать API как представление общих ресурсов изменилась. В то время как ожидается, что API-интерфейсы будут использоваться в качестве общего инструмента многими приложениями и пользователями, они считаются службами и обычно требуют более контролируемой разработки и развертывания.

SOA и микросервисы являются примерами сервисных API. Сервисы – самая горячая тенденция в API, до такой степени, что возможно, что все API в будущем будут рассматриваться как представляющие сервисы.

Недостатки OpenAPI и Swagger UI

Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:

Информация только о ссылке: Во-первых, спецификация OpenAPI и выходные данные Swagger UI охватывают только документацию ссылки. OpenAPI предоставляет основу каждой конечной точки: описание, параметры, пример запроса и ответа. OpenAPI не содержит места для описания начала работы, информации о том, как получить ключи API, как запустить пример приложения, информацию об ограничениях скорости или о сотне других деталей, которые находятся в гайдах для разработчиков. Поэтому, несмотря на то, что есть этот крутой интерактивный инструмент, позволяющий пользователям исследовать и изучать наш API, мы все равно должны предоставить руководство пользователя. По аналогии, вывод Javadoc или Doxygen для основанной на библиотеке API не научит пользователей, как на самом деле использовать наш API. Нам все еще нужно описать сценарии использования класса или метода, объяснить, как настроить код, что делать с ответом, как устранить неполадки и т.д. Короче говоря, писать реальные справочные и пошаговые руководства.
Избыточность / дублирование информации: В OpenAPI потенциально есть два места, где описываются конечные точки и параметры (описание ссылки Swagger UI и руководство пользователя), и нужно либо синхронизировать их, встроить одно в другое, или иным образом указать связь между ними. Подробнее разберемся в разделе Интеграция Swagger с собственной документацией.
Сложность рабочего процесса API: Сложность API также может создать ограничение в Swagger. Питер Грюнбаум, опубликовавший несколько учебных пособий по документированию API для Udemy, говорит, что автоматизированные инструменты, такие как Swagger, работают лучше всего для простых API. Если есть конечные точки, которые имеют сложные взаимозависимости и требуют специальных рабочих процессов настройки или другой не интуитивной обработки, простой характер пробного интерфейса Swagger может, вероятно, заставить пользователей почесать голову. Например, если нужно сначала настроить службу API, прежде чем конечная точка что-либо возвратит, а затем использовать одну конечную точку, чтобы получить определенный объект, который передается в параметры другой конечной точки, и т.д., функции в Swagger UI не будет иметь большого смысла для пользователей без подробного руководства.
Запросы к реальным данным: Некоторые пользователи могут не осознавать, что нажатие кнопки создает реальные вызовы для их собственных учетных записей на основе используемых ими ключей API. Смешивание использования исследовательской изолированной программной среды, такой как Swagger, с реальными данными может впоследствии создать головные боли, когда пользователи начнут спрашивать, как можно удалить все тестовые данные или почему их фактические данные теперь испорчены. Для этих сценариев лучше всего настроить песочницу или тестовую учетную запись для пользователей. Но это легче сказать, чем сделать. Можно обнаружить, что компания не предоставляет «песочницу» для тестирования API. Все вызовы API выполняются только для реальных данных.
Ограничения CORS: Можно столкнуться с ограничениями CORS (Cross-Origin Resource Sharing — обмен ресурсами между источниками) при выполнении вызовов API. Не все API принимают запросы, выполненные с веб-страницы. Если вызовы не выполняются, нужно открыть консоль JavaScript и проверить, не блокирует ли CORS запрос. Если это так, нужно попросить разработчиков внести коррективы, чтобы учесть запросы, инициированные из JavaScript на веб-страницах. .
Проблематика обширных параметров тела запроса: конечные точки с длинными параметрами тела запроса, как правило, проблематичны. Один API может включать запросы с параметрами тела запроса длиной в сотни строк (тело запроса использовалось для настройки сервера API). С таким параметром тела запроса отображение пользовательского интерфейса Swagger оказалось непригодным для использования. Команда вернулась к гораздо более примитивным подходам (таким как таблицы) для перечисления всех параметров и их описания.

Есть ли технологии для устного перевода?

Если в письменном переводе на помощь профессионалам приходит множество программ и технологий, то сфера устного перевода, будь то синхронный или последовательный перевод, все еще опирается на профессиональные навыки переводчика.

Такое решение разрабатывает наша компания. Оно позволяет при помощи смартфона или планшета осуществлять видеоудаленный перевод.

Такие сервисы существуют и на Западе. Например, в США есть аналоги, которые начали формироваться в то же время, что и наш сервис. Одна из крупнейших компаний Language Line, ранее занимавшаяся телефонным переводом, стала внедрять услугу видеоперевода и видеоперевода с языка жестов. Компания Purple также занимается переводом с языка жестов, в том числе предлагая и видеоперевод. В свою очередь Certified Languages International запустила видеоудаленный перевод после 20 лет устных и телефонных переводов.

Видеоудаленный перевод – это следующий шаг в развитии этой отрасли и уже очевидно, что это направление будет развиваться и дальше.

Параметры строки запроса

Параметры строки запроса указываются после знака вопроса В конечной точке. Знак вопроса, параметры, которые следуют за ним и их значения, называется «строкой запроса». В строке запроса каждый параметр перечисляется один за другим с амперсандом , разделяющим их. Порядок параметров строки запроса не имеет значения.

Эта строка запроса:

или эта

вернут один и тот же результат.

Однако в параметрах path порядок имеет значение. Если параметр является частью фактической конечной точки (не добавляется после строки запроса), это значение обычно описывается в описании самой конечной точки.

Библиотеки не нужны

В описании к Ć сказано, что в его случае зависимости от библиотек рантайма (runtime libraries) сведены к минимуму. В качестве примера Фусик привел вывод кода, для использования в программах на С – в большинстве случаев пользователь получает автономную пару файлов .c/.h с удобочитаемым кодом С99.

Презентация Ć в 2013 году

Автор утверждает, то это в равной степени относится и к другим поддерживаемым языкам – C++, C#, Java, JavaScript, Python, Swift и OpenCL. В то же время он упоминает о нескольких исключениях. Одно из них касается необходимости использования библиотеки GLib для вывода кода на C в случае, когда программист, пишущий на Ć, использует выражения List, Dictionary или SortedDictionary.

Примеры API

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

Google Календарь

Google Calendar API взаимодействует с приложениями, связанными с бронированием, организацией мероприятий и иными событиями, для которых нужно выделять время. Приложение синхронизирует данные из нескольких сервисов и позволяет просматривать, редактировать и удалять информацию о будущих событиях в одном месте.

Например, пользователь заказал билет на самолет или на концерт. Google Calendar API автоматически добавит дату и время полета или мероприятия в календарь.

Погодные приложения

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

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

Сервис по заказу авиабилетов

Билеты на самолет можно купить на сайте авиакомпании, но есть специальные сервисы, которые помогают найти подходящий рейс на указанные даты по выгодной цене. Агрегатор отбирает данные с разных сайтов и показывает ее в одном окне. В России по такому принципу работает известный агрегатор Aviasales.

Чтобы быстро собирать актуальную информацию, разработчики приложения для покупки билетов пользуются API сервисов авиакомпаний.

Умный сервис сквозной аналитики от Calltouch так же работает по умному принципу: система объединяет данные о разных маркетинговых мероприятиях компании и создает информативные и понятные отчеты. Закажите сквозную аналитику и сократите бюджет на бесполезную рекламу.

Сквозная аналитика

от 990 рублей в месяц

Автоматически соберет данные с рекламных площадок, сервисов и CRM в 1 окне
Бесплатные интеграции c CRM и другими сервисами: более 50 готовых решений
Анализируйте воронку продаж от показов до кассы
Оптимизируйте свой маркетинг с помощью подробных отчетов: дашборды, графики, диаграммы
Кастомизируйте таблицы, добавляйте свои метрики. Стройте отчеты моментально за любые периоды

Узнать подробнее

Кнопки авторизации

Часто сайты, где нужно зарегистрироваться, предлагают для авторизации использовать аккаунт на популярных площадках – , Google, ВКонтакте. Эти функции тоже выполняет API. С помощью кнопок авторизации сайт запрашивает данные о вашем аккаунте на стороннем ресурсе. После обмена информацией, сайт авторизует пользователя.

Навигация на сайтах и в приложениях

По аналогии с работой погодных приложений, другие сервисы тоже пользуются данными программных интерфейсов. Спутники предоставляют геоданные для тех или иных приложений. С ними работает API, проецируя на графический интерфейс карту. Эта карта используется не только в приложениях-навигаторах, но и в сервисах для вызова такси или заказа курьерской доставки.

Зачем нужен API?

Теперь нам знакомы принципы работы API и задачи, которые они помогают решить. Но они хороши не только этим. Программные интерфейсы используются еще по двум немаловажным причинам.

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

Во-вторых, на API можно заработать. Например, сервисы, предоставляющие информацию с метеовышек, берут плату за каждый запрос актуальной погоды, если их API используется в сторонних приложениях. Аналогичные условия могут предлагать и другие компании, предоставляющие услуги. Будь то навигация, конвертация файлов в другие форматы и прочие возможности, реализуемые через API.

Почему разработчики используют API?

Есть как минимум еще 4 причины, объясняющие интерес программистов к API:

API упрощает и ускоряет создание новых продуктов. Разработчикам не приходится каждый раз изобретать велосипед. Можно взять API нейронной сети TenserFlow, к примеру, и внедрить в свое программное обеспечение, а не создавать собственную систему машинного обучения.
Как я уже отметил выше, программный интерфейс увеличивает безопасность разработки. С помощью него можно вынести ряд функций в отдельное приложение, сделав невозможным их некорректное использование. От человеческого фактора это тоже спасает.
API упрощает настройку связей между разными сервисами и программами. Интерфейс нивелирует необходимость в тесном сотрудничестве создателей различных приложений. Разработчики могут внедрять поддержку сторонних сервисов, вообще не контактируя с их создателями.
Наличие готовых интерфейсов позволяет сэкономить не только время и силы программистов, но и финансы, с которыми часто связано создание новых программных решений.

Проверка спецификации

При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.

Если допустить ошибку при написании кода в редакторе Swagger, можно быстро исправить ее, прежде чем продолжить, вместо того, чтобы ждать запуска сборки и устранять ошибки.

Для формата спецификации у нас есть выбор работы JSON или YAML. Пример кода выше находится в YAML. У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки , как в других языках разметки, таких как XML.

YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человека. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.

Примеры параметров

Скриншот ниже является примером раздела параметров с Box API:

Пример параметра BOX API

В этом примере параметры сгруппированы по типу:

параметры path,
параметры запроса,
параметры тела.

Конечная точка также выделяет параметр path распознаваемым образом в определении конечной точки.

Часто параметры просто перечислены в таблице или списке определений, как в этом примере:

Параметр	Обязательно/Опционально	Тип данных
format	Optional	String

Вот пример документации API Yelp

Можно форматировать значения различными способами, кроме таблицы. При использовании списка определений или другого не табличного формата, обязательно нужно разработать стили, которые сделают значения легко читаемыми.

Визуализация спецификации OpenAPI с помощью Swagger UI

После того, как получился действующий документ по спецификации OpenAPI, описывающий API, можно “скормить” эту спецификацию различным инструментам, чтобы проанализировать ее и сгенерировать интерактивную документацию, аналогичную примеру Petstore.

Наиболее распространенным инструментом, используемым для анализа спецификации OpenAPI, является Swagger UI. (Помните, что «Swagger» относится к инструментам API, тогда как «OpenAPI» относится к независимой от поставщика спецификации, не зависящей от инструмента.) После загрузки пользовательского интерфейса Swagger его довольно легко настроить с помощью собственного файла спецификации. Руководство по настройке Swagger UI есть в этом разделе.

Код пользовательского интерфейса Swagger генерирует экран, который выглядит следующим образом:

На изображении видно, как Swagger отображает спецификацию Open API

Можно ознакомиться с примером интеграции Swagger UI с примером API сервиса погоды, использованным в качестве примера курса.

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

Один язык для всех

Польский программист Петр Фусик (Piotr Fusik) создал новый язык программирования Ć, своего рода универсальный язык написания кода. Со слов автора, его творение позволяет писать код, который в дальнейшем можно будет без труда использовать в других языках.

В качестве примера Фусик привел C, C++, C#, Java, JavaScript, Python, Swift и OpenCL. Все детали своего языка Ć, который пока находится на одном из этапов разработки, он опубликовал в открытом виде на GitHub (принадлежит Microsoft).

Петр Фусик не уточнил, почему назвал свое творение именно так, и не сообщил, как правильно его произносить. «Апостроф» над буквой С называется «акут», то есть, с учетом этого, название языка может звучать как «Си с акутом». Также это буква польского алфавита, которая называется «Че» и читается приблизительно как «Ч».

Запуск коллекций с помощью Collection Runner

Давайте запустим коллекцию с помощью Collection Runner.

Шаг 1: Нажимаем на кнопку «Runner» (находится рядом с кнопкой Import)

Шаг 2: Должна будет открыться следующая страница:

Разберем основные элементы:

2 — Resent Runs: Все предыдущие запуски

3 — Environment: Окружение. Если вы хотите запустить коллекцию в конкретном окружении, вы можете выбрать его в этом поле.

4 — Iterations: Количество итераций

5 — Delay: Задержка. Указывается в миллисекундах. Выполнение тестов без задержки может вызвать ошибки, поэтому всегда указывайте небольшую задержку.

7 — Start Run: Кнопка для запуска коллекции

Шаг 3: В этом окне добавим коллекцию для запуска. Выбираем нашу коллекцию тестов, устанавливаем параметр Iterations в 2, delay в 2500ms и нажимаем кнопку запуска.

Шаг 4: После выполнения откроется отчет. В нашей коллекции были GET и POST запросы, но тесты мы добавляли только для GET-запроса. Поэтому в отчете рядом с POST-запросом показывается текст «This request doesn’t have any tests.» (для этого запроса нет тестов)

Как работают API?

API-интерфейсы состоят из двух связанных элементов. Первый – это спецификация, описывающая, как происходит обмен информацией между программами в форме запроса на обработку и возврата необходимых данных. Второй – это программный интерфейс, написанный в соответствии с этой спецификацией и каким-то образом опубликованный для использования.

Считается, что программное обеспечение, которое хочет получить доступ к функциям и возможностям API, «вызывает» его, а программное обеспечение, которое создает API, «публикует» его.

API-интерфейсы авторизуют и предоставляют доступ к данным, которые запрашиваются пользователями и другими приложениями. Доступ аутентифицируется для службы или части функциональных возможностей по предопределенным ролям, которые определяют, кто или какая служба может получить доступ к определенным действиям или данным. API также предоставляют контрольный журнал, в котором подробно описывается доступ к системе: кто или что и когда.

Приложения, вызывающие API, традиционно писались на определенных языках программирования. Веб-API можно вызывать через любой язык программирования, но также можно получить доступ к веб-страницам, созданным в HTML или инструментах генератора приложений.

Наиболее распространенными архитектурами API являются передача репрезентативного состояния (REST) и простой протокол доступа к объектам (SOAP), который определяет стандартную спецификацию протокола связи для обмена сообщениями на основе XML. SOAP требует меньше кода, связанного с инфраструктурой низкого уровня, чем REST, но REST API легче масштабировать и повторно развертывать, проще реализовать и интегрировать с веб-сайтами и службами. Текущая отраслевая тенденция в основном заключается в использовании REST API, особенно для веб-взаимодействий.

Ну и что? Just Do It!

Действительно. Языки программирования всё же возможно переводить автоматически. Для этого есть специальные программы — транспайлеры. Они переводят исходный код в рамках одного и того же уровня или абстракции — например, Python в JS (оба языка высокоуровневые) или JS ES2015 в JS ES5.

Фото: Public Domain

Одним из первых транспайлеров можно считать Ratfor — язык программирования, который расширяет возможности Fortran 66 — в частности, предоставляет операторы if-else и while. Он появился в середине 1970-х и, по сути, переводил программы, написанные на Fortran 66, на более современные стандарты языка.

Однако автоматические переводчики с разных языков стали создавать в конце 1980-х. Тогда появился Fortran-to-C Converter (F2C) — программа, которая переводит код с Fortran на C. Другой яркий пример — Pascal to C Translator (P2C), который транслирует Pascal в C.

Правда, F2C и P2C создавали под конкретную задачу — портирование приложений между разным железом и операционными системами. Первый переводил важные программы с уже мёртвого языка программирования на живой. Второй — портировал их на ПО Unix, созданное на Pascal: для этого программу также было необходимо перевести на C. То есть ни один из транспайлеров не делался именно для того, чтобы легко переводить любую программу с одного языка на другой.

Как работают транспайлеры

Компиляция большинства языков программирования включает шаг «‎взять текст программы и преобразовать его в синтаксическое дерево».

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

Но чаще всего траспайлер преобразует текст программы на другом языке, так что программисту нужно для каждого узла синтаксического дерева подобрать нужный текст на целевом языке. К примеру, если компилятор Python увидел код:

if foo:

print (foo)

то он построит из него синтаксическое дерево с корнем if, от которого идут ветки «условие» и «тушка». Преобразуя это в JavaScript, разработчик транспайлера пишет код, который для ветки if создаст следующий текст:

if () {

}

Далее внутрь круглых скобок устанавливается транспилированное условие, а внутрь фигурных — транспилированная «туша».

Ну и так далее. Всего будет примерно сотня разных узлов. Плюс преобразования для ситуаций, когда в исходном языке есть что-то, чего нет в целевом. Тогда генерируется код, который делает то же по смыслу, но в форме, которая доступна целевому языку.

Григорий Петров

Генералист, нейрофизиолог-любитель. Организует разработку, конференции, хакатоны. Участвовал в создании Radmin и Advanced IP Scanner, продвигал интерактивное телевидение NPTV и программируемую телефонию Voximplant. Сейчас — head of developer relations в Evrone.

Параметры тела запроса

Часто с запросами POST (где мы что-то создаем) мы отправляем объект JSON в теле запроса. Этот параметр и есть тело запроса. Обычно форматом тела запроса является JSON. Этот JSON объект может быть длинным списком пар ключ-значение с несколькими уровнями вложенности.

Например, конечной точкой может быть что-то простое, например . Но в тело запроса мы можем включить объект JSON со многими парами ключ-значение, например:

Документирование параметров тела сложного запроса

Документирование данных JSON (как в параметрах тела запроса, так и в ответах) является одной из самых сложных частей документации API. Документирование JSON объекта будет легким, если этот объект прост, с несколькими парами ключ-значение на одном уровне. Но если у нас есть JSON объект с несколькими объектами внутри объектов, множественными уровнями вложенности и большими объемными данными, это может быть сложно. И если объект JSON занимает более 100 строк, или 1000, нам необходимо тщательно продумать, как представить информацию.

Таблицы хороши для документирования JSON, но в них трудно различать элементы верхнего уровня и подуровня. Объект, который содержит объект, который также содержит объект, и другой объект и т. Д., Может сбивать с толку.

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

Взгляните на ресурс eBay findItemsByProduct. Вот параметр тела запроса (в данном случае формат XML):

Ниже параметра тела запроса находится таблица, которая описывает каждый параметр:

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

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

Подход Swagger к параметрам тела запроса

Пользовательский интерфейс Swagger, который мы рассмотрим позже, а также его демо, предоставляет другой подход к документированию параметра тела запроса. Swagger UI показывает параметры тела запроса в формате, который вы видите ниже. Интерфейс Swagger позволяет переключаться между представлением «Пример значения» и представлением «Модель» для ответов и параметров тела запроса.

Посмотрим на Swagger Petstore для изучения. “Пример значения” показывает образец синтаксиса вместе с примерами. При нажатии на ссылку “Модель””, видим пример параметра тела запроса и описания каждого элемента.

Модель включает в себя переключатели «развернуть / свернуть» со значениями. (Демо Petstore не имеет множество описаний параметров в модели, но если включить описания, они будут отображаться в модели, а не в примере значения.)

Tip: Мы познакомимся с Swagger более подробно в разделе Знакомство со спецификациями OpenAPI и Swagger. А пока сосредоточимся на этих основных элементах справочной документации API. Мы увидим, что эти же разделы появляются в спецификации OpenAPI.

Можно заметить, что существует множество вариантов документирования JSON и XML в параметрах тела запроса. Правильного способа документировать информацию нет. Как всегда, выбираем метод, который отображает параметры нашего API наиболее простым и легким для чтения способом.

Если у нас относительно простые параметры, наш выбор не будет иметь большого значения. Но если сложные, громоздкие параметры, то, возможно, придется прибегнуть к пользовательским стилям и шаблонам, чтобы представить их более четко. Исследуем эту тему более подробно в разделе Пример и схема ответа.

Типы API

По типу доступа программные интерфейсы API бывают:

Внутренние. Используют только сотрудники компании. Нужны для решения внутренних задач организации: снижения расходов и отладки процессов.
Партнерские. Создают для партнеров и клиентов компании. Применяют для разработки веб-продуктов и сокращения издержек.
Публичные. Их создают для привлечения внимания и продвижения веб-продукта и компании, продаж, разработки новых сервисов и приложений.

WEB API, которые используют для создания HTTP-служб:

RPC (Remote Procedure Call).

Использовалась, когда системы были связаны в локальных сетях. Принцип работы: вызов удаленных систем похож на вызов функций внутри программы. Яркие примеры таких систем – CORBA и DCOM.

SOAP (Simple Object Access Protocol).

Это протокол для обмена сообщениями в распределительной вычислительной среде. Помимо удаленного вызова процедур, SOAP способен отправлять и получать сообщения формата XML. Работает с протоколами прикладного уровня.

REST (Representational State Transfer).

Это архитектура ПО для веб-служб. Обеспечивает работу с любыми форматами, будь то сайт, flash-программа, приложение другого формата и другие. Благодаря тому, что данные передаются без дополнительных слоев, REST использует меньше ресурсов, так как на каждую передачу данных требует меньше запросов.

Параметризация запросов

Параметризация — одна из самых полезных особенностей Postman.

Часто необходимо выполнить один и тот же запрос на разных наборах данных. С помощью параметризации, можно использовать переменные при выполнении запросов.

В Postman, параметры создаются с помощью двойных скобок: `test`.

Например, наш base URL — https://testengineer.ru и мы сохраняем это значение в переменной с именем base_url. В этом случае, мы можем обратиться к этой переменной из запроса, написав `base_url`. Для того, чтобы отправить запрос на этот URL, мы подставим эту переменную в запрос. Выглядеть это будет так: `base_url`/get?customers=new. Запрос будет отправлен на https://testengineer.ru/get?customers=new

Шаг 1: Меняем тип HTTP-запроса на GET и вводим URL:

Шаг 2: Меняем URL на параметр `url`. После этого URL запроса должен быть таким: `url`/users

Шаг 3: Теперь нам нужно создать переменную окружения, чтобы использовать ее в качестве параметра. Для этого нажимаем на кнопку с глазом и кликаем на Edit (редактировать), чтобы создать глобальную переменную и затем использовать ее в коллекциях.

Шаг 4: В окне создания переменной задаем имя (именем будет url) и значение (значением будет https://jsonplaceholder.typicode.com). После этого нажимаем Save (Сохранить)

Шаг 5: Возвращаемся к GET-запросу и нажимаем Send (отправить)

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

API explorer обеспечивает интерактивность с нашими собственными данными

Многие API имеют функцию API Explorer, которая позволяет пользователям делать реальные запросы непосредственно из документации. Например, вот типичная справочная страница для документов API Spotify:

API Flickr также имеют встроенный API Explorer:

Как и API New York Times:

API Explorer позволяет вставлять свои собственные значения, свой собственный ключ API и другие параметры в запрос, чтобы увидеть ответы непосредственно в API Explorer. Возможность видеть свои собственные данные делает ответ более реальным.

Однако, если у вас нет нужных данных в вашей системе, использование собственного ключа API может не показать вам полный возможный ответ. Это работает лучше всего, когда ресурсы включают публичную информацию, а запросами являются запросы GET.

Запуск коллекций с помощью Newman

Для того, чтобы запустить коллекции с помощью Newman, делаем следующее:

Шаг 2: Открываем командную строку и выполняем команду

Шаг 3: После установки newman заходим в Postman. В списке коллекции находим нашу коллекцию, нажимаем на три точки и выбираем Export (Экспортировать)

Шаг 4: В появившемся окне выбираем «Export Collection as Collection 2.1 (Recommended)» и нажимаем Export.

Шаг 5: Выбираем папку, в которую экспортировать коллекцию и нажимаем Save. Рекомендуем создать отдельную папку для Postman-тестов. После нажатия на Save, коллекция будет экспортирована в выбранную папку.

Шаг 6: Для корректного запуска нам понадобится экспортировать и окружение. Для этого нажимаем на кнопку с глазом и выбираем опцию Download as JSON. Выбираем папку, в которую экспортировать окружение и нажимаем Save. Рекомендуем экспортировать окружение в ту же папку, в которую была экспортирована коллекция.

Шаг 7: Теперь, когда мы экспортировали коллекцию и окружения в папку, возвращаемся в командную строку и меняем директорию на ту, где находятся коллекция и окружение.

Например:

Шаг 8: Запускаем коллекцию с помощью команды:

После выполнения коллекции, появятся результаты выполнения тестов.

Выполнение преобразования текста

Преобразование текста можно достичь, создав запрос GET к API в . В примере приложения метод вызывает процесс преобразования текста:

Метод создает URI запроса и извлекает маркер доступа из службы маркеров. Затем запрос на перевод текста отправляется в API, который возвращает XML-ответ, содержащий результат. XML-ответ анализируется, и результат преобразования возвращается вызывающему методу для вывода.

дополнительные сведения о интерфейсах api для преобразования текста см. в разделе API перевода текстов.

Настройка преобразования текста

Процесс преобразования текста можно настроить, указав параметры HTTP-запроса:

Этот метод задает текст для перевода и язык перевода текста. список языков, поддерживаемых Переводчик Майкрософт, см. в разделе поддерживаемые языки в API Переводчик Майкрософт текста.

Примечание

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

Идет отправка запроса

Метод делает запрос GET к преобразованию текста REST API и возвращает ответ:

Этот метод создает запрос GET, добавляя маркер доступа к заголовку с префиксом строки . Затем запрос GET отправляется в API, с URL-адресом запроса, который указывает текст для перевода, и язык, на который нужно перевести текст. Затем ответ считывается и возвращается вызывающему методу.

API отправит код состояния HTTP 200 (ОК) в ответе при условии, что запрос действителен, что означает, что запрос выполнен успешно и запрошенные сведения находятся в ответе. Список возможных ответов об ошибках см. в разделе ответные сообщения при получении.

Обработка ответа

Ответ API возвращается в формате XML. В следующих XML-данных показано типичное сообщение об успешном ответе:

В примере приложения XML-ответ разбивается на экземпляр, при этом корневое значение XML возвращается вызывающему методу для отображения, как показано на следующих снимках экрана: