Collection для ReadLater Starter

1. History vs Collection

Поиск и детали уже удалось руками прочитать в Postman. Теперь другая проблема: удачный запрос легко остаётся случайной победой, если он живёт только в History.

Ручные сценарии уже понятны; теперь им нужен устойчивый дом. Если этого не сделать, через пару дней вы снова будете вспоминать, какой именно query отправляли и почему тот ответ казался «правильным». Collection как раз превращает разовые удачи в повторяемый набор сценариев.

Сохраняем сценарий

Когда новичок слышит «сохрани запрос», он часто думает, что мы сохраняем «вот этот красивый JSON, который пришёл». На самом деле мы сохраняем сценарий: действие, которое можно повторить. Сценарий в HTTP почти всегда определяется не только URL, но и методом, query‑параметрами, заголовками, а иногда и body. И если вы сохраняете только «где-то в голове было /search?q=...», вы сохраняете не сценарий, а настроение.

Представьте, что запрос — это рецепт. В рецепте важно не только «было вкусно», а точные ингредиенты и шаги: сколько соли, какая температура, сколько минут. Точно так же в Postman полезный saved request — это ваш рецепт HTTP‑вызова. Он включает метод, точный путь, параметры и, если нужно, заголовки вроде Accept. А ещё он может содержать короткую заметку о том, что именно считается успехом: какой статус ожидается и какая верхнеуровневая форма ответа вам нужна для ReadLater Starter.

Чтобы почувствовать идею «сценарий, а не случайность», можно даже описать saved request как маленькую структуру (это не код проекта, а иллюстрация мышления):

// Пример мыслительной модели: "сценарий HTTP-вызова", а не кусок JSON-ответа
public record HttpScenario(String name, String method, String pathTemplate) { }

HttpScenario details = new HttpScenario(
        "Get book details by external id", // человекочитаемое имя сценария
        "GET",                             // HTTP-метод
        "/books/{externalId}"              // шаблон пути, а не конкретный ID
);

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

2. Имена запросов: смысл вместо test 1

Название запроса — это мелочь ровно до того момента, пока запросов не стало больше трёх. А потом внезапно выясняется, что new request (4) не отвечает на фундаментальный вопрос: «что именно он делает и зачем он мне нужен?». И здесь Postman тонко троллит новичков: интерфейс позволяет сохранять запрос хоть как угодно, но мозг потом расплачивается процентами.

Хорошее имя запроса — это короткая фраза, которая объясняет сценарий без открытия вкладок. Обычно оно строится как «действие + объект + критерий». Например, не Search, а Search books by query, потому что поиск чего? по чему? где? И не Details, а Get book details by external id, потому что детали чего и по какому идентификатору? Чем конкретнее, тем меньше вы будете гадать через неделю.

Вот небольшой «анти‑словарь» и «словарь», который можно держать в голове:

Если хочется формализовать для себя (да, программистам иногда приятно, когда всё похоже на структуру), то можно представить «имя» как часть контракта:

// Имя запроса — это тоже часть контракта: по нему вы потом ищете сценарий в коллекции
public record RequestName(String value) {
    public static RequestName of(String v) {
        // В реальном проекте тут обычно ещё проверяют null/blank,
        // но для иллюстрации нам достаточно trim()
        return new RequestName(v.trim());
    }
}

RequestName good = RequestName.of("Search books by query (q=...)");
RequestName bad  = RequestName.of("test 1"); // так делать не надо: смысла ноль

Это смешной пример, но мысль серьёзная: имя запроса — это ваш будущий «поиск по памяти».

3. Папки в collection: по сценариям

Когда в коллекции появляются несколько запросов, возникает следующий соблазн: «давайте разложим по методам: GET‑папка, POST‑папка…». Это выглядит логично ровно одну минуту. Потом вы понимаете, что вам нужно найти «поиск каталога», а не «какой-то GET». В ReadLater Starter мы думаем сценариями: поиск книг, получение деталей, а позже — уже в другой фазе проекта — локальный reading list API. Поэтому папки должны отражать смысл, а не технику.

Для текущего дня нам достаточно двух папок: одна для поиска, другая для деталей. Это простая структура, которая масштабируется: когда вы добавите ещё 1–2 сценария, вы поймёте, куда они ложатся. А когда вы откроете коллекцию через месяц, вы не будете расшифровывать «зачем тут семь GET‑ов», вы увидите: «ага, каталог → поиск, каталог → детали».

Удобно сразу представить будущую структуру визуально (дерево — почти как структура пакетов в Java, только без компилятора, который вас спасёт):

ReadLater Starter — External Book Catalog API
├─ Catalog Search
│  └─ Search books by query (q=...)
└─ Catalog Details
   └─ Get book details by external id

Если хочется ещё более «наглядно‑инженерно», можно представить поток так, как вы будете его проходить глазами:

flowchart TD
    %% Папки в коллекции -> порядок, в котором человек обычно проходит сценарий
    %% Сначала ищем, затем по найденному externalId идём в детали
    A["Catalog Search folder"] --> B["Search books by query"]
    B --> C["Из ответа получаем externalId (пока просто глазами)"]
    C --> D["Catalog Details folder"]
    D --> E["Get book details by external id"]

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

4. Сохранение: Save vs Save As

В Postman есть очень удобная ловушка: вы можете легко создать копию запроса, чуть‑чуть поменять параметр, снова копию, снова поменять… и вот у вас коллекция превращается в кладбище клонов. Это особенно часто происходит, когда страшно «сломать рабочий запрос». Но ломать не надо — надо понимать, как поддерживать один канонический сценарий.

Здесь полезно держать в голове простое правило: если вы улучшили существующий запрос (например, поправили URL, добавили понятный заголовок Accept, исправили имя), вы сохраняете изменения в этот же запрос через обычный Save. Если же вы действительно делаете другой сценарий (например, поиск по другой ручке, другой endpoint), тогда имеет смысл Save As и новый самостоятельный запрос с новым именем. Идея простая: «новый смысл — новый запрос; улучшение старого смысла — обновление существующего запроса».

Ещё одна практическая привычка: не держать «копию на всякий случай» как основной способ безопасности. С Postman это приводит к вечному final-final-reallyfinal. Если вам страшно, что вы потеряете исходную версию, лучше используйте аккуратную дисциплину: сначала переименуйте запрос в понятный вид, потом вносите изменения, потом сохраняйте. И если всё-таки нужен «снимок», то пусть это будет осознанное действие и осознанное имя вроде Search books by query (baseline), а не десятая копия без смысла.

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

5. Description: мини-документация

Когда вы сохраняете запрос, вам хочется верить, что «и так всё понятно, там же URL написан». Но реальность такая: через неделю вы открываете запрос и не помните, что именно считали важным в ответе. Особенно если JSON большой, а вам нужна из него только пара полей. Поэтому очень полезно использовать Description прямо у запроса или у папки: буквально 2–5 строк текста, которые фиксируют, что это за сценарий и что вы в нём увидели.

Важно не превратить это в роман и не начать писать «полную документацию провайдера». Нам нужно ровно то, что пригодится проекту ReadLater Starter: какой параметр задаёт запрос, какой статус считается успехом, и какая верхняя форма ответа (список/объект). Такое описание потом легко превращается в карту контракта рядом с репозиторием.

Например, для запроса поиска Description может выглядеть примерно так (как текст, не как код):
«Scenario: search by query. Query param: q. Success: 200 OK. Response: JSON object with items (array) and count (number). Important fields per item: title, author, externalId.»

Если хочется чуть более «структурно», можно мысленно держать шаблон заметки:

// Короткий снимок контракта: что за сценарий, какой статус ок и какая форма ответа
public record ContractSnapshot(String scenario, int okStatus, String responseShape) { }

ContractSnapshot snapshot = new ContractSnapshot(
        "Search books by query (q=...)", // что делаем
        200,                             // какой статус считаем успехом
        """
        Object: { items: [...], count: number }
        """                              // верхнеуровневая форма ответа
);

Это не надо переносить в код проекта. Это просто удобный «каркас мысли», который помогает писать короткие описания без воды.

6. Итоговый вид коллекции

Сейчас задача простая: сделать collection маленькой, но взрослой — такой, чтобы рядом с проектом лежали два понятных и воспроизводимых сценария каталога.

Представьте себе, что вы открываете Postman и видите одну коллекцию, в которой ровно две папки и по одному запросу в каждой. Имена запросов читаются как мини‑предложения. Внутри запросов стоят те параметры, которые отражают сценарий, а не «что попало». И самое важное: вы можете закрыть Postman, открыть завтра и повторить то же самое без восстановления «по памяти».

Вот пример минимального набора, который соответствует нашему домену:

Заметьте, что в имени поиска мы не фиксируем clean code как будто это часть сценария навсегда. Это просто пример значения. Сценарий — «поиск по запросу», а не «поиск именно clean code». Если вам нужно держать пример значения, лучше пусть оно живёт в самом запросе (в query), а не в названии.

И ещё один нюанс, который сильно помогает новичкам: если вы работаете с провайдером, у которого есть несколько похожих ручек, добавляйте маленький префикс в названия. Например, Catalog: Search books by query и Catalog: Get book details.... Это не обязательно, но иногда спасает, когда в коллекции появляются другие источники.

7. Типичные ошибки при работе с коллекциями

Ошибка №1: оставлять всё в History и считать, что «потом найду».
Обычно так происходит, когда запрос «вроде работает» и хочется быстрее двигаться дальше. Но история — это не структура, а временный след. Через день вы начнёте заново искать тот самый удачный запрос, и обучение превратится в повторение одного и того же. Коллекция нужна именно для того, чтобы знание не испарялось после закрытия Postman.

Ошибка №2: бессмысленные названия запросов вроде test 1 или new request.
Это классический баг новичка: кажется, что название не важно, потому что «я же помню». А потом запросов становится пять, и вы уже ничего не помните, особенно если они все GET и выглядят похожими. Хорошее имя — это не украшение, а экономия времени и нервов. В реальных проектах такие имена ломают командную работу, а в учебном проекте ломают вашу собственную память.

Ошибка №3: папки по HTTP‑методам вместо папок по сценариям.
Сначала кажется логичным разложить по GET/POST, потому что это «объективный признак». Но это группировка по технике, а не по смыслу. Вам нужно быстро находить «поиск каталога» и «детали книги», а не «какой-то GET». Когда вы группируете по сценариям, коллекция начинает выглядеть как карта продукта, а не как набор протокольных упражнений.

Ошибка №4: плодить десятки копий одного запроса «на всякий случай».
Такое случается из страха что-то испортить: вы делаете копию, меняете параметр, снова копия… и внезапно не знаете, какая версия правильная. В Postman лучше держать один канонический запрос на один сценарий и обновлять его через Save, а Save As использовать только когда вы действительно создаёте новый сценарий, а не «поиграться с параметром».

Ошибка №5: вшивать конкретное значение параметра в имя запроса.
Название вроде Search clean code кажется удобным, пока вы не захотите искать другую книгу. Потом появляются Search ddd, Search kafka, Search spring… и вы случайно создаёте не коллекцию сценариев, а коллекцию «моих вчерашних мыслей». Сценарий — это шаблон («поиск по query»), а значения — это детали одного запуска.