Создание API-запросов в Postman

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

Содержание

• Создание и отправка API-запросов
• Отправка параметров и данных в теле API-запроса
• Настройка заголовков для API-запросов
• Загрузка файлов
• Выбор пользовательских настроек для API-запросов
• Группировка запросов с помощью коллекций Postman
• Генерация сниппетов кода из API-запросов

Подпишитесь на наш ТЕЛЕГРАМ КАНАЛ ПО АВТОМАТИЗАЦИИ ТЕСТИРОВАНИЯ

Создание и отправка API-запросов

API-клиент Postman позволяет отправлять API-запросы с помощью HTTP, GraphQL, gRPC и других распространенных протоколов. Вы можете отправлять параметры и основные данные вместе с запросами, а также отправлять заголовки запросов, если того требует ваш API. Вы также можете настроить пользовательские параметры для каждого запроса.

Создание нового запроса

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

Вы можете создать новый запрос из рабочего простанства (workspace), используя New > HTTP, или нажав на + для открытия новой вкладки.

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

Чтобы протестировать отправку запроса в Postman, можно указать эндпоинт Postman Echo (https://postman-echo.com/get и метод GET), а затем нажать Send.

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

Выбор протокола запросов

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

Помимо HTTP, Postman поддерживает отправку запросов по протоколам GraphQL, gRPC, WebSocket, MQTT, и SOAP.

Имейте в виду, что вы не сможете изменить протокол запроса после нажатия на кнопку Сохранить.

Указание URL-адреса запроса

Каждый запрос, который вы отправляете в Postman, требует URL, представляющий эндпоинт API, с которым вы работаете. Каждая операция, которую вы можете выполнить с помощью API, обычно требует определенный эндпоинт. А каждый эндпоинт API доступен по определенному URL. Именно его вы вводите в Postman для доступа к API.

• Если вы создаете API, то URL обычно представляет собой базовое местоположение плюс путь. Например, в запросе https://postman-echo.com/get часть https://postman-echo.com – это базовый URL, а /get – путь к эндпоинту.
• Если вы используете API сторонних разработчиков, ваш поставщик API предоставит необходимые вам URL-адреса, например, в своей документации для разработчиков.

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

Postman автоматически добавит http:// в начало вашего URL, если вы не укажете протокол.

Вы можете ввести параметры запроса в поле URL или на вкладке Params. Если в запросе используются параметры пути, их можно ввести в поле URL. В запросах можно использовать кодировку URL. Все это мы разберем в этой статье.

Выбор метода запроса

По умолчанию Postman для нового запроса выбирает метод GET. Он обычно используется для получения данных из API. Вы можете использовать множество других методов для отправки данных в API, включая следующие:

• POST – добавление новых данных
• PUT – замена существующих данных
• PATCH – обновление некоторых существующих полей данных
• DELETE – удаление существующих данных

Например, если вы работаете с API для приложения со списком задач, вы можете использовать метод GET для получения текущего списка. Затем при помощи метода POST можно создать новую задачу, а при помощи методов PUT или PATCH – отредактировать существующую.

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

 .

Один и тот же эндпоинт может принимать различные методы. Например, API может иметь эдпоинт POST /customer для добавления нового клиента и эдпоинт GET /customer для получения существующего клиента.

Отправка запроса

После указания протокола, метода и URL-адреса запроса добавьте любые другие сведения, требуемые API, к которому вы отправляете запрос:

• Укажите любые параметры и данные в теле запроса или заголовки, которые необходимо отправить вместе с запросом (это мы рассмотрим далее)
• Настройте необходимую аутентификацию и авторизацию
• Вы также можете использовать файлы cookie в своих запросах, нажав на кнопку Cookies  (под кнопкой Send)

После ввода всех данных запроса нажмите на кнопку Send, чтобы отправить запрос на сервер API. Вы можете просмотреть ответ от сервера в панели ответа. Узнать больше о структуре ответа API в Postman можно здесь.

Просмотреть отправленные вами запросы и отправить их снова можно в Истории (History) на боковой панели. Вы также можете сохранять и упорядочивать запросы в коллекции.

Как поделиться своими запросами

Вы можете поделиться созданными вами запросами с коллегами. Нажмите на иконку с тремя точками

рядом с запросом, затем нажмите на кнопку Поделиться (Share). Узнать больше о том, как делиться созданными вами запросами с коллегами в Postman, можно здесь.

Отправка параметров и данных в теле API-запроса

Postman позволяет отправлять данные вместе с HTTP-запросами. Вы можете добавлять различные параметры запроса (query parameters) и пути (path parameters) и указывать их значения. Добавлять данные в тело запроса можно в различных форматах, включая данные формы (FormData), raw и binary.

Отправка параметров

Вы можете указать путь и параметры запроса, используя поле URL или вкладку Params:

• Параметры запроса добавляются в конец URL-адреса, после ?. Они перечисляются в виде пар ключ-значение, разделенных символом & следующим образом: ?id=1&type=new
• Параметры пути являются частью URL-адреса и прописываются с помощью плейсхолдеров, которым предшествует :, как в данном примере: /customer/:id

Чтобы указать параметр запроса, добавьте его непосредственно в URL или выберите вкладку Params и введите его имя и значение. Когда вы вводите параметры запроса, эти значения обновляются повсюду, где они используются в Postman.

Чтобы указать параметр пути, введите имя параметра в поле URL после двоеточия, например :id. Когда вы введете параметр пути, Postman отобразит его во вкладке Params, где вы также сможете его отредактировать.

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

Когда вы закончите вводить параметры, нажмите на кнопку Отправить (Send) чтобы отправить запрос.

Отправка данных в теле запроса

Вам нужно отправлять тело запроса, когда вы хотите добавить или обновить данные. Например, если вы отправляете запрос на добавление нового клиента в базу данных, вы можете прописать данные о клиенте в JSON. Обычно данные в теле запроса необходимы для методов PUT, POST и PATCH.

Во вкладке Body можно указать данные, которые необходимо отправить вместе с запросом. Можно отправлять различные типы данных в соответствии с требованиями вашего API.

Отправляя данные в теле запроса, важно правильно выбрать заголовки, указывающие вашему API на тип содержимого (это может ему понадобиться для обработки полученных данных):

• Для form-data и urlencoded Postman автоматически прикрепляет соответствующий заголовок Content-Type.
• Если вы используете raw, Postman установит заголовок в зависимости от выбранного вами типа данных (например, text или json).
• Если вы вручную выберете заголовок Content-Type, это значение будет иметь приоритет над тем, что установит Postman.
• Postman не устанавливает тип заголовка для binary.

По умолчанию Postman выбирает None для данных в теле запроса. Оставьте это значение, если вам не нужно отправлять тело запроса. В противном случае выберите необходимый тип данных: form-data, URL-encoded, raw, binary или GraphQL.

Form-data

Различные формы сайтов часто отправляют данные в API в виде multipart/form-data. Вы можете повторить это в Postman, используя опцию form-data во вкладке Body вашего запроса. Тип form-data позволяет отправлять пары ключ-значение и указывать тип содержимого.

Вы также можете прикрепить файл с помощью form-data и отправить его вместе с запросом. Выберите File в выпадающем списке рядом с именем ключа (key name), а затем выберите файл, который хотите отправить. Можно выбрать файл из вашей локальной системы, и Postman сохранит путь к файлу в запросе.

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

URL-кодировка

Если вашему API требуются URL-кодированные данные, выберите тип x-www-form-urlencoded во вкладке Body вашего запроса. Введите пары ключ-значение, и Postman закодирует их перед отправкой запроса.

Raw

Тип raw можно использовать для отправки всего, что можно ввести в виде текста. Во вкладке Body вашего запроса выберите опцию raw и используйте выпадающий список, чтобы указать формат данных (Text, JavaScript, JSON, HTML или XML). Postman включит подсветку синтаксиса и добавит соответствующие заголовки к вашему запросу.

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

В теле запроса можно использовать переменные, и Postman будет подставлять их текущие значения.

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

Binary

Вы можете использовать тип binary data для отправки вместе с телом запроса информации, которую нельзя ввести вручную в редакторе Postman. Речь может идти об изображениях, аудио- и видеофайлах, но можно также отправлять и текстовые файлы.

Во вкладке Body вашего запроса выберите вариант binary, а затем выберите файл, который вы хотите отправить вместе с запросом. Вы можете выбрать файл из вашей локальной системы, и Postman сохранит путь к файлу в запросе.

GraphQL

Вы можете отправлять запросы GraphQL вместе с запросами Postman, выбрав опцию GraphQL во вкладке Body вашего запроса. Введите свой код в поле Query и любые переменные в поле GraphQL Variables.

Ознакомьтесь с более подробной информацией о GraphQL в Postman.

Настройка заголовков для API-запросов

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

Заголовки настраиваются во вкладке Headers вашего запроса. Введите все необходимые пары ключ-значение, и Postman отправит их вместе с запросом. По мере ввода текста Postman предлагает вам различные опции, которые можно использовать для автозаполнения настроек, например Content-Type.

Пресеты заголовков

Вы можете сохранить часто используемые заголовки в пресетах (preset). Во вкладке Headers вашего запроса выберите выпадающий список Presets и нажмите на кнопку Manage Presets (Управление пресетами). Нажмите Add Header Preset, чтобы добавить новый пресет, и введите его название. Введите пары ключ-значение и нажмите Add (Добавить).

Вы можете выбрать необходимый пресет в выпадающем списке Presets. Выбор пресета приведет к автозаполнению полей в заголовках запроса.

Заголовки, генерируемые автоматически

Postman будет автоматически добавлять определенные заголовки к вашим запросам в зависимости от выбранных вами параметров и настроек запроса. Выберите hidden (скрытые) в верхней части вкладки Headers для получения информации о том, что Postman будет отправлять с вашим запросом.

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

Внести изменения в заголовок можно во вкладках Authorization, Body, во вкладке Cookies для домена запроса, в настройках, а в некоторых случаях и на самой вкладке Headers запроса.

Если заголовок был добавлен в соответствии с настройками авторизации, выберите вкладку Authorization,  чтобы изменить его. Чтобы изменить заголовки cookie, измените настройку Cookies для домена, к которому вы отправляете запрос.

Чтобы отключить автогенерируемый заголовок во вкладке Headers, отмените выбор чекбокса. Если хотите изменить заголовок, добавьте новую запись, указав название заголовка в поле Key и свое значение в поле Value.

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

Для заголовков Content-Length и Content-Type Postman автоматически вычислит значения при отправке запроса, основываясь на данных во вкладке Body. Однако вы можете изменить оба значения вручную.

Загрузка файлов

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

О хранении тестовых данных

Вы можете прикрепить файл с тестовыми данными к запросу при использовании типов form-data или binary. Postman сохранит путь к файлу из вашего локального рабочего каталога и использует его при отправке запроса. Однако если вы поделитесь запросом в рабочем пространстве, локальный файл не будет передан. Это означает, что другие члены команды не смогут отправить запрос, если не поместят копию того же файла в свой собственный локальный рабочий каталог.

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

Чтобы сделать возможным совместное использование запросов, в которых используются файлы тестовых данных, вы можете загрузить эти файлы в вашу рабочую команду в Postman. Загруженные файлы будут доступны всем членам вашей команды. Их можно будет применять для отправки запросов, которые используются в рабочем пространстве совместно. Загруженные файлы также доступны для запросов, отправляемых из мониторов и при запланированных запусках коллекции. Еще они могут быть использованы из Postman Flows и Postman CLI  (но не Newman).

Загрузка файлов для вашей команды в Postman

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

Чтобы загрузить файл для вашей команды в Postman, сделайте следующее:

1. Откройте запрос и выберите вкладку Body.

2. Выберите тип form-data или binary в зависимости от типа данных, которые вы хотите отправить с запросом.

3. Если вы прикрепляете form-data, выберите File в выпадающем списке рядом с названием ключа.

4. Выберите файл тестовых данных, который вы хотите использовать для запроса:

• Чтобы использовать локальный файл, нажмите + New file from local machine. Выберите файл и нажмите Open. Поддерживаются следующие форматы файлов: CSV, JSON и binary.
• Чтобы использовать файл, который был загружен ранее, выберите его в списке. Можно использовать любой файл, загруженный членом вашей команды. Чтобы найти файл, начните вводить его имя.

5. Чтобы загрузить файл, нажмите на значок загрузки 

 рядом с файлом и намите Upload. Размер загружаемых файлов не должен превышать 5 МБ.

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

Загруженные файлы можно использовать в любых запросах, созданных вами или другими членами вашей команды (за исключением публичных рабочих пространств). К загруженным файлам также могут обращаться Postman Flows и Postman CLI при автоматизации выполнения запросов.

Выбор пользовательских настроек для API-запросов

В Postman можно настроить множество параметров для запросов к API. Эти параметры позволяют настроить поведение Postman при отправке запроса. Например, вы можете включить проверку SSL-сертификата или отключить URL-кодировку.

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

URL-кодировка

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

Процессор будет кодировать символы в зависимости от того, где они встречаются в URL:

Компонент URL	Символы для кодирования
Path	" < > ` # ? { } SPACE
Query	" # & ' < = > SPACE
Userinfo	" < > ` # ? { } / : ; = @ [ \ ] ^

Процессор включен в Postman по умолчанию, но вы можете отключить кодировку, если работаете с необычной реализацией сервера. Чтобы включить или выключить эту настройку в запросе, выберите во вкладке Settings параметр Encode URL automatically (Автоматическое кодирование URL).

Вы можете выборочно кодировать части URL, выделив текст и щелкнув правой кнопкой мыши, а затем выбрав EncodeURIComponent.

Группировка запросов с помощью коллекций Postman

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

Выберите Collections в боковой панели, чтобы просмотреть список коллекций в текущем рабочем пространстве. О том, как создавать коллекции, читайте в этой статье.

Генерация сниппетов кода из API-запросов

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

Postman может генерировать сниппеты кода для различных языков программирования и фреймворков, включая C#, JavaScript и NodeJS.

Чтобы сгенерировать сниппет кода:

1. Откройте запрос, который вы хотите использовать для сниппета, затем выберите значок кода </> в правой панели.

2. Выберите язык или фреймворк из выпадающего списка.

3. Выберите значок копирования 

, чтобы скопировать фрагмент кода в буфер обмена.

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

 рядом с выпадающим списком. Настройки зависят от выбранного языка или фреймворка.

Поддерживаемые языки и фреймворки

Postman поддерживает следующее:

Язык	Фреймворк
C	LibCurl
C#	HttpClient
C#	RestSharp
cURL	cURL
Dart	Dart
Go	http package
HTTP	(Raw HTTP request)
Java	OkHttp
Java	Unirest
JavaScript	Fetch
JavaScript	jQuery
JavaScript	XHR
NodeJS	Axios
NodeJS	Native
NodeJS	Request
NodeJS	Unirest
Objective-C	NSURLSession
OCaml	Cohttp
PHP	cURL
PHP	Guzzle
PHP	Http_Request2
PHP	pecl_http
PowerShell	RestMethod
Python	http.client (Python 3)
Python	Requests
R	httr
R	RCurl
Ruby	NET::Http
Shell	Httpie
Shell	wget
Swift	URLSession

Перевод статьи «Create and send API requests in Postman».