Змінні та baseUrl у Postman

1. Копіпаста URL та її наслідки

Поки запитів один чи два, здається логічним просто вставити повний URL і жити щасливо. Але колекція в Postman дуже швидко зростає: з’являються різні варіанти пошуку, запити до різних деталей, перевірки різних параметрів — і ви раптово розумієте, що «просто вставити URL» перетворюється на копіпасту з десятків рядків. А копіпаста в інженерії — це як пісок у зубах: терпимо перші 30 секунд, а потім хочеться запитати: «Навіщо я взагалі це роблю?».

Уявіть, що у вас у колекції 12 запитів, і в кожному жорстко прописана адреса сервісу. Провайдер змінив домен, або ви вирішили тестувати через проксі, або вам дали staging-адресу — і ви починаєте вручну виправляти одне й те саме 12 разів. У процесі ви обов’язково десь пропустите один запит, а потім пів години будете шукати, чому «все працює, крім одного». Спойлер: тому що один залишився зі старим доменом.

Порівняймо «як було» і «як стає», коли ми вводимо змінні:

# Було (жорстко і крихко): адреса та параметри привʼязані до рядка
https://catalog.example.com/search?q=clean+code&limit=3

# Стало (шаблон, який можна використовувати повторно): адреса та значення живуть окремо
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

У першому рядку зашито все: і адресу, і параметри. У другому рядку URL перетворюється на читабельний шаблон: адреса сервісу окремо, пошукова фраза окремо, ліміт окремо. І тепер «змінити адресу» — це не переписати 12 запитів, а змінити одне значення в середовищі.

2. Середовища та активне середовище

Слово «середовище» звучить так, ніби ми зараз відкриємо портал у DevOps і почнемо обговорювати Kubernetes. Ні, сьогодні все простіше й приємніше. У Postman середовище (environment) — це набір змінних, які підставляються в запити замість {{...}}. Можна думати про нього як про коробку з наклейкою: «Для цього сервісу адреса така, ліміт такий, решта значень — теж свої».

Ключова ідея в тому, що один і той самий запит може виконуватися з різними наборами значень. Для цього в Postman є поняття активного середовища: ви обираєте його в інтерфейсі, зазвичай у правому верхньому куті, і всі ваші {{var}} починають посилатися саме на значення з обраного середовища. Не обрали середовище — змінні або не підставляться, або підставляться не так, як ви очікували, і вийде класична помилка: «Усе ж правильно, чому не працює?».

Щоб не плутатися, корисно тримати в голові маленьку «карту місцевості» й розуміти, хто за що відповідає:

Окремий маленький, але важливий нюанс: у Postman у змінної часто є два значення — Initial і Current. Навіть якщо ви не працюєте в команді, корисно розуміти цей зміст. Initial — це значення «за замовчуванням» (часто те, що потрапляє в експорт), а Current — те, що реально використовується у вас локально просто зараз. Якщо ви колись побачите, що змінна «нібито заповнена», але підставляється порожнеча, насамперед перевірте, де саме заповнено: в Initial чи в Current.

3. baseUrl і базова адреса API

baseUrl — це не магічне слово і не особлива можливість Postman. Це просто домовленість: ми виносимо в змінну спільну адресну основу сервісу, щоб не повторювати її в кожному запиті. І це одна з тих маленьких звичок, які несподівано роблять вас людиною, у якої не розвалюється колекція через тиждень.

Що зазвичай входить у baseUrl? Як правило, це scheme + host (+ port), іноді ще базовий префікс шляху, якщо в API він фіксований. Приклади:

# Варіант 1: API живе з кореня домену (тільки схема + хост)
baseUrl = https://catalog.example.com

# Варіант 2: API живе під префіксом (схема + хост + спільний префікс шляху)
baseUrl = https://catalog.example.com/api

Чого в baseUrl бути не повинно? У ньому не повинно бути конкретних endpoint-ів (/search, /books/...) і не повинно бути query-параметрів (?q=...). Якщо ви кладете в baseUrl /search?q=..., то ви не створюєте базу — ви просто переносите крихкість в інше місце.

Окрема тема — як домовитися про слеші, бо саме на слешах ламається половина початкових колекцій. Краще одразу обрати правило і дотримуватися його, інакше ви рано чи пізно зберете монстра на кшталт https://catalog.example.com//search і будете дивитися на нього з питанням: «Це взагалі законно?».

У курсі зручно зафіксувати правило: baseUrl зберігається без завершального /, а шляхи в запитах починаються з /. Тоді склеювання завжди передбачуване:

# У середовищі: baseUrl без завершального слеша
baseUrl = https://catalog.example.com

# У запиті: шлях починається зі слеша
шаблон  = {{baseUrl}}/search

# Підсумковий рядок після підстановки змінних
результат = https://catalog.example.com/search

Це виглядає нудно, але нудно — це добре. Нудно — значить, передбачувано. А передбачувано — значить, не ламається в найневдаліший момент.

Невелика схема, щоб закріпити ідею:

flowchart LR
    %% Postman підставляє значення з активного середовища в шаблон запиту
    E["Середовище: baseUrl, searchQuery, limit"] --> T["Шаблон запиту {{baseUrl}}/search?..."]
    T --> S[Надіслати]
    S --> R["Справжній запит https://.../search?..."]

Postman робить просту річ: бере шаблон, підставляє значення з активного середовища й відправляє вже «справжній» HTTP-запит.

4. Які значення виносити в змінні

На цьому етапі легко впасти в дві крайності. Перша крайність — винести тільки baseUrl, а все інше продовжувати міняти вручну в URL. Друга крайність — винести взагалі все на світі, включно з «улюбленою літерою автора курсу» й «настроєм вашого кота», а потім не розуміти, що звідки береться.

Здоровий підхід дуже практичний: виносьте в змінні те, що або часто повторюється, або часто змінюється, або використовується в кількох запитах. У нашому каталожному сценарії це зазвичай searchQuery і limit. Трохи пізніше з’явиться змінна для ідентифікатора книги, наприклад bookId (поки можна задавати її вручну, просто щоб бачити, як вона підставляється).

Ось мінімальний «набір новачка», який уже робить колекцію зручною:

{
  // Базова адреса сервісу: змінюється під час перемикання стенду/проксі
  "baseUrl": "https://catalog.example.com",

  // Пошукова фраза: зручно змінювати, не чіпаючи сам запит
  "searchQuery": "clean code",

  // У Postman змінні зберігаються як рядки — це нормально для query-параметрів
  "limit": "3",

  // Ідентифікатор книги: стане у пригоді для запитів до деталей
  "bookId": "BK-101"
}

Зверніть увагу на лапки навколо limit. У Postman значення змінних — це рядки. Навіть якщо ви логічно думаєте «ліміт — число», у середовищі воно зберігається як "3". Це нормально. Сервіс на іншому боці все одно отримає query-параметр як рядок і сам перетворить його на число, якщо він так улаштований.

Ще один тонкий, але важливий момент про імена: краще називати змінну за змістом, а не за тим, як називається параметр в URL. Параметр може бути q, але змінну краще нехай буде searchQuery, тому що через тиждень ви забудете, що таке q, а searchQuery забудете лише якщо матимете амнезію.

5. Шаблони змінних і читабельність

Синтаксис {{variableName}} у Postman — це просто «підстав значення змінної сюди». Важливо те, що це працює не лише в рядку URL, а й в інших місцях запиту: у query params, у headers і навіть у body, якщо ви відправляєте JSON. Сьогодні ми не будемо ускладнювати, але корисно знати, що змінні — це універсальна підстановка.

Найчастіший спосіб — вставити змінні прямо в URL. Це швидко й наочно:

# Шаблон запиту: Postman підставить значення змінних з активного середовища
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

Але є спосіб ще акуратніший, особливо для новачків: залишити URL «чистим», а query-параметри задавати в таблиці Params. Тоді Postman сам правильно збере ? і &, а ще акуратно закодує пробіли та спецсимволи. Зміст виглядає так:

# URL без query-параметрів: параметри краще задавати в Params
URL: {{baseUrl}}/search

А параметри — як таблиця:

У підсумку ви отримуєте запит, який читається майже як документація: «йдемо на /search, передаємо q і limit». І ви менше ризикуєте помилитися в знаках ?, &, зайвих пробілах і всіх інших «символах долі», які ламають запит саме тоді, коли ви хочете просто спокійно вчитися.

Для запиту деталей книги шаблон зазвичай ще простіший і красивіший:

# Деталі книги: змінна bookId підставиться в шлях
{{baseUrl}}/books/{{bookId}}

Тут дуже добре видно, чому змінні корисні: сам endpoint читається як «деталі книги за id», а конкретне значення bookId живе окремо. І це буде особливо приємно, коли ви почнете перемикати середовища: запит не змінюється, змінюються тільки значення.

6. Дисципліна імен і форматів

У Postman немає «архітектурної поліції», яка прийде й скаже, що ви назвали змінну неправильно. Тому дисципліна тут з’являється не тому, що «так треба за стандартом», а тому, що інакше ви самі собі влаштуєте квест на уважність. Особливо в навчальному проєкті, де важлива відтворюваність: ви маєте завтра відкрити колекцію й зрозуміти її без довгих пошуків.

Найчастіша проблема — хаос в іменах. В одному запиті {{url}}, в іншому {{host}}, у третьому {{apiUrl}}, а в четвертому взагалі {{baseURL}} (з іншою літерою). Postman чесно спробує підставити, але якщо змінної не існує, він просто не зможе. Підсумок виглядає так: «запит дивно підсвічується, і сервер не відповідає». Секрет у тому, що ви викликали змінну, якої немає.

Друга класика — різні правила про слеші в різних середовищах. Наприклад, в одному середовищі baseUrl = https://catalog.example.com/ (зі слешем), а в іншому baseUrl = https://catalog.example.com (без слеша). Якщо запити написані як {{baseUrl}}/search, то в першому середовищі вийде //search. Іноді сервер «проковтне» подвійний слеш, іноді ні, іноді проксі поводитиметься дивно. Краще не перевіряти, наскільки терплячий ваш сервер, а зробити правило єдиним.

Третя проблема — спроба покласти в baseUrl занадто багато. У baseUrl кладуть /search, а іноді навіть ?limit=3. Потім намагаються зробити запит до деталей, і починається: «А як тепер це все склеювати?». Відповідь проста: ніяк. baseUrl має бути базою, а не половиною конкретного запиту.

Якщо ви хочете зробити колекцію читабельною, мов книжка, зручна традиція — домовитися про мінімальний набір імен і дотримуватися їх у всіх запитах каталогу: baseUrl, searchQuery, limit, bookId. Не тому, що це єдині правильні слова, а тому, що єдині слова — це відсутність зайвого шуму.

7. Перемикання середовищ та адрес

Один із головних бонусів середовищ ви відчуєте не відразу, а тоді, коли з’явиться потреба: «Ось цей самий запит, але до іншого джерела». Це може бути інший домен, інший стенд, інший проксі або просто тимчасова підміна сервісу. І замість того, щоб переписувати URL у кожному запиті, ви просто перемикаєте активне середовище.

Дуже зручно завести хоча б два середовища вже зараз, навіть якщо друге — «навчальне». Наприклад:

Важливо: ми поки не обговорюємо, що саме стоїть за alt і як там улаштовані відповіді. Нам тут важливий принцип: запити залишаються шаблонами, а «куди стріляємо» визначається середовищем.

І ось тут з’являється маленький щоденний ритуал Postman-розробника: перед натисканням Send ви на секунду перевіряєте, яке середовище активне. Це схоже на те, як ви в Java-проєкті перевіряєте, що запускаєте правильну конфігурацію (dev, test, prod), тільки тут усе простіше: один спадний список.

Ще одна звичка, яка рятує нерви: користуватися переглядом змінних середовища (у Postman це зазвичай іконка у вигляді ока поруч із вибором середовища). Ви відкриваєте список і швидко бачите: чому дорівнює baseUrl, чому дорівнює searchQuery. Якщо там порожньо — значить, запит не винен; винне середовище або те, що ви його не обрали.

8. Типові помилки під час роботи зі змінними

Коли починаєте працювати зі змінними, перші проблеми майже завжди однакові, і це навіть добре: їх легко навчитися розпізнавати. Якщо ви заздалегідь знаєте ці граблі, то не провалитеся в них по коліно, а акуратно переступите й підете далі, зберігши гордість і час.

Помилка № 1: адреса сервісу жорстко прописана в кожному запиті.
Це виглядає невинно, поки запитів мало, але швидко перетворюється на лотерею: «Де я забув змінити домен?». Лікується просто: виносьте спільну частину в baseUrl, а всі запити пишіть через {{baseUrl}}/.... Тоді зміна адреси — це зміна однієї змінної, а не полювання на копіпасту.

Помилка № 2: одне й те саме значення називають різними словами (url, host, apiUrl).
Проблема не в самих словах, а в тому, що мозок людини обмежений: він не зобов’язаний пам’ятати, що apiUrl і host у вас означають одне й те саме. Оберіть одне ім’я (у курсі — baseUrl) і тримайтеся його скрізь. Це робить колекцію читабельною і знижує шанс, що ви випадково звернетеся до неіснуючої змінної.

Помилка № 3: в одному середовищі baseUrl зі слешем наприкінці, в іншому — без нього.
Через це запити починають збиратися по-різному: десь один слеш, десь два, десь узагалі «склеїлося без слеша». Краще заздалегідь зафіксувати правило (наприклад, baseUrl завжди без завершального /) і дотримуватися його в усіх середовищах. Тоді шаблони URL працюватимуть однаково.

Помилка № 4: у baseUrl кладуть зайве — query-параметри або конкретний endpoint.
Якщо в baseUrl лежить /search?q=..., ви вже не будуєте запити — ви починаєте жонглювати рядками. Зберігайте в baseUrl тільки адресну основу сервісу, а шлях і параметри тримайте в запиті, бажано через Params. Інакше колекція стає крихкою.

Помилка № 5: забувають обрати активне середовище перед відправкою запиту.
Це найлюдськіша помилка: ви все налаштували, але Postman усе одно відправляє «не туди» або не підставляє змінні. Перед Send на секунду перевіряйте, яке середовище активне, і за потреби відкривайте швидкий перегляд змінних. Це займає дві секунди й економить десять хвилин роздратування.