Postman Collections

Prev Next

So far you've been firing off one request at a time and throwing the result away when you close Postman. That doesn't scale — a real RecipeBox API has login requests, recipe CRUD requests, and search requests, and you'll want to run all of them together, share them with another tester, or hand them to a CI pipeline later. A Postman Collection is a saved, organized group of requests (plus their example responses, scripts, and documentation) that lives in your Postman workspace instead of disappearing the moment you close the tab. This lesson builds a RecipeBox API collection from scratch and organizes it the way a real test suite would be organized.

What a Collection Actually Is

Think of a collection as a folder of saved requests, with three things layered on top of the raw HTTP call:

Piece	What it holds
The request itself	Method, URL, headers, body — exactly what you already built for `GET /recipes` or `POST /recipes`
Tests / scripts	Any assertions or pre-request scripts attached to that request (covered in later lessons)
Saved example response	A snapshot of a real response, useful for documentation and for teammates who haven't hit a live server yet
Documentation	Markdown notes on the collection, a folder, or an individual request, explaining what it does and why

Collections are stored as JSON under the hood, which is why they can be exported, checked into version control, imported by a teammate, or run headlessly with Newman (a later lesson in this track).

Creating the "RecipeBox API" Collection

In Postman, click New → Collection (or the + next to the Collections tab in the sidebar).
Name it RecipeBox API.
Open the collection's Description box (Edit → Description) and add a short summary — see the documentation section below.

You now have an empty container. The next step is deciding how to organize requests inside it instead of dumping everything at the top level.

Organizing With Folders

A collection can contain folders, and folders can contain requests (or more folders). For the RecipeBox API, group requests by the resource or concern they touch rather than by HTTP method — it mirrors how the API itself is organized and makes the collection easy to navigate as it grows:

Folder	Requests inside
Auth	POST `/auth/login`
Recipes	GET `/recipes`, GET `/recipes/{id}`, POST `/recipes`, PUT `/recipes/{id}`, DELETE `/recipes/{id}`
Search	GET `/recipes/search?q=...`

To create a folder: right-click the RecipeBox API collection in the sidebar → Add Folder → name it (Auth, Recipes, or Search). Repeat for all three before you start saving requests into them.

Note: Folders don't change how a request behaves — they're purely organizational. A GET inside Recipes runs identically to one sitting at the collection root. The value is entirely for humans (and for the Collection Runner, which can run "just this folder" — covered later in this track).

Saving a Request Into a Collection

Every request you build in Postman starts out unsaved in a scratch tab. To make it part of the RecipeBox API collection:

Build the request as usual, e.g. GET {{baseUrl}}/recipes/42 (we'll wire up that {{baseUrl}} variable in the next lesson).
Click Save (or Ctrl+S).
In the Save dialog, give it a clear name — Get Recipe By ID, not Request 2.
Choose the destination folder: RecipeBox API → Recipes.
Click Save to RecipeBox API.

Repeat this for every request as you build it: Login and Login (Bad Password) in Auth; List Recipes, Get Recipe By ID, Create Recipe, Update Recipe, and Delete Recipe in Recipes; Search Recipes in Search. Naming requests by what they test — not just the raw method and path — pays off the moment the collection has more than a handful of requests.

Collection-Level Documentation

A collection's Description field accepts Markdown and shows up whenever the collection is viewed, shared, or published. For a shared team collection like RecipeBox, treat it as the README for your API tests:

# RecipeBox API — Test Collection

## Base URL
Uses the `{{baseUrl}}` variable — set per environment (Dev / Staging / Prod).
See the "Environments & Variables" lesson.

## Folders
- **Auth**    — login and token retrieval
- **Recipes** — CRUD on the Recipe resource (id, title, ingredients, steps, photoUri, category, prepMinutes, isPublished)
- **Search**  — keyword search over recipe titles

## Conventions
- Every request has at least one `pm.test()` assertion.
- Requests that need auth read the `{{token}}` variable set by "Login".

Individual folders and requests can carry their own shorter descriptions too — for example, the Create Recipe request's description might just note which fields are required versus optional. Good collection documentation is what lets a new tester (or your future self) understand the suite without opening every request one by one.

Where this is going: Right now every request still has a hardcoded URL like https://api.recipebox.example.com/recipes/42. The next lesson, Environments & Variables, replaces that with {{baseUrl}} so the exact same collection can run against dev, staging, or production with a single click.

Prev Next