2.2 Основные запросы

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

Для начала давайте попробуем отправить основные типы HTTP запросов.

Создадим новый запрос. Для этого в верхнем меню нужно выбрать File > New...

В появившемся окне в разделе Building Blocks выбираем HTTP Request. Либо можно рядом с существующими вкладками запросов нажать + и создать новую вкладку.

GET запрос.

Попробуем отправить GET запрос.

GET - это один из основных методов HTTP протокола. Обычно такой тип запросов используется для чтения данных. В GET запросе клиент запрашивает определенный ресурс, который находится на сервере, и получает ответ от сервера в виде содержимого ресурса.

https://petstore.swagger.io/v2/store/inventory

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

Первая из них базовый(base) URL - это https://petstore.swagger.io. Она состоит из протокола https. Здесь чаще всего будет использоваться либо https, либо http протокол. Затем идёт host, представленный доменным именем petstore.swagger.io. Вместо него также может быть использован ip адрес хоста. И затем идет неявно указанный порт, в нашем случае это 443. Указанный неявно - означает, что если вы добавите к запросу порт : https://petstore.swagger.io:443, ничего не изменится т.к. этот же порт используется по умолчанию для протокола https. Если же ваш запрос использует протокол http, порт по умолчанию будет 80. Если порт отличается от используемых по умолчанию, потребуется явно указать его через двоеточие.

Вторая часть это путь(path) запроса. Он находится сразу после base url.

После ввода URL мы можем отправить запрос. Для этого нужно нажать кнопку Send. Через некоторое время после этого в нижней части главного окна мы увидим ответ от сервера. Его содержимое мы рассмотрим позже, а пока давайте перейдем к другим запросам.

GET запрос с path параметрами

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

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

Таким образом, использование параметров в HTTP методах позволяет уточнить цели запроса, определить необходимые данные для выполнения операции и передать их на сервер. Это делает HTTP методы более гибкими и позволяет использовать их в различных сценариях, связанных с передачей данных через Интернет. В этом примере мы рассмотрим path параметры.

https://petstore.swagger.io/v2/pet/:id

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

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

В данном примере мы будем использовать API для получения информации от домашнем питомце по его идентификатору в системе. Его мы будем передавать на сервер с помощью path параметра id. После отправки такого запроса, в ответе от сервера придёт информация о питомце, который имеет переданный нами идентификатор.

В Postman для добавления такого параметра в запрос, необходимо указать двоеточие перед его именем. После этого он появится на вкладке Params, в таблице path параметров. Там же затем можно будет задать его значение в столбце value. Оно будет использовано во время отправки запроса на сервер. Если path параметр присутствует в запросе, он является обязательным. При попытке оставить его значение пустым, в ответе от сервера вы увидите ошибку.

В таблице Path Variables кроме value, присутствует поле description. В нем вы можете добавить описание к каждому из параметров. Столбцы value и description можно убрать из таблицы. Для этого нужно нажать на три точки в правой части таблицы. В появившемся меню оставить галки только возле полей, которые нужно показывать в таблице параметров.

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

Такой запрос будет аналогичен предыдущему и вернёт такой же ответ от сервера, не смотря на другое имя path параметра. Мы можем даже передать значение через URL, не используя дополнительных параметров.

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

GET запрос с query параметрами

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

https://petstore.swagger.io/v2/pet/findByStatus?status=available

Query параметры - параметры строки запроса. В HTTP-запросах они представляют собой дополнительные данные, которые передаются в URL-адресе и используются для передачи на сервер, значение для фильтрации, поиска, сортировки и т.д. Query-параметры могут использоваться вместе с любым HTTP-методом, но наиболее часто они используются с методом GET.

От основной части url эти параметры отделяются знаком вопроса, а между собой знаком амперсанда. Каждый параметр представляет собой пару из имени и значения, разделенную знаком равенства. Имена и значения могут быть закодированы, используя механизм URL-кодирования, чтобы избежать ошибок при передаче специальных символов.

В данном примере мы используем запрос, который позволяет нам получить информацию о домашних питомцах отфильтрованную по одному из статусов. Значение статуса для фильтрации передается через query параметр. Его имя status, а значение available.

Если ввести такой параметр в строке запроса, он автоматически появится на вкладке Params, в таблице Query Params. Если добавить его на вкладке Params, тогда он появится в строке запроса. Еще на этой вкладке у каждого параметра есть поле description. В нем можно добавить описание к каждому из указанных параметров.

Как и для path параметров, здесь столбцы value и description можно скрыть. Для этого нужно нажать кнопку View more actions и выбрать только нужные поля.

Path и query параметры можно как совмещать внутри одного запроса, так и использовать по отдельности. В отличии от path, query параметры могут быть как обязательными так и необязательными. Обычно это указано в спецификации api метода. Например в нашем случае, query параметр status является обязательным. Поэтому выполнение запроса без него приведет к ошибке.

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

https://petstore.swagger.io/v2/user/login?username=admin&password=123

https://petstore.swagger.io/v2/user/login?password=123&username=admin

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