For four modules we have been building the Aroma Store API: we designed it in module 2, built it in module 3 and hardened it in module 4. And all that time we have tested it in two ways: with curl by hand, typing endless headers into the terminal, and with the automated Supertest tests from 03-08, which are excellent for the code but useless for exploring.

A third way of working is missing, the one that fills the real working day of anyone who develops or consumes an API: open a client, fire a request, look at the response, change a parameter, fire it again. And, when something works, save it so you never have to type it again or rely on someone remembering the exact syntax.

This lesson opens module 5 with that tool. We are going to build the "Aroma Store v1" collection: a versionable file, with folders per resource, environments for local, test and production, authentication that renews itself, assertions that check the contract and chained requests. And we will finish by running the whole thing from the terminal with Newman, which is exactly what 05-05 will wire into continuous integration.

All the data, domains and credentials in this lesson are fictional. No string that looks like a token is a real secret, and no example should be copied with real values inside it.

1. Why you need an HTTP client as well as automated tests
2. What Postman is and what alternatives exist
3. Installation and first contact: GET /v1/coffees
4. Reading the response: body, headers and timings
5. Collections and folders: the structure of "Aroma Store v1"
6. The real requests from the contract
7. Variables: collection, environment and global
8. Environments: local, test and production
9. Secrets: what never gets exported
10. Authentication: Bearer Token and folder inheritance
11. Pre-request scripts: what happens before sending
12. Post-response scripts: the assertions
13. Chaining requests: saving the id and using it later
14. Generating a different Idempotency-Key on every send
15. Assertions against the JSON schema
16. Running the whole collection with the Collection Runner
17. CSV and JSON data files
18. Newman: the collection from the terminal
19. Importing openapi.yaml and exporting the collection
20. Documentation and sharing with the team
21. Postman's mock server
22. Best practices and what goes into the repository

The tests from 03-08 and a client like Postman answer different questions, and confusing them leads to teams that have one and sorely miss the other.

The key sentence is the last row. Supertest would never see that the production load balancer is stripping the Aroma-Trace-Id header, because there is never a load balancer: it calls app directly. And Postman would not detect a regression if nobody presses the button. That is why the goal of this lesson is not "learn to press Send", but to turn manual exploration into a repeatable, executable artefact that, in 05-05, will press itself.

Postman is an HTTP client with a graphical interface that stores requests in collections: JSON files with the URLs, headers, bodies, variables and scripts. That detail —that a collection is a file— is what makes it more than a personal tool: it is versioned in Git, reviewed in a pull request and run in continuous integration.

These are the serious alternatives you will come across in real teams:

A practical comparison of the same request in the three terminal forms:

And the same case as a .http file for the REST Client extension, which has the advantage of living inside the repository next to the code it tests:

How to choose. If your team already lives in Postman, stay in Postman: the gain from switching rarely pays for itself. If what matters most to you is that requests get reviewed as code in pull requests, Bruno or REST Client are better because they store readable plain text. Everything conceptual in this lesson —variables, environments, chaining, assertions, running in CI— exists in all four graphical tools under another name; what changes is the syntax.

We will use Postman because it is the de facto standard and because Newman gives us the CI execution that 05-05 needs.

Postman is downloaded from its official site for Windows, macOS and Linux; there is also a web version, although to call localhost it needs the Postman Agent installed, so for our case the desktop application is the better option.

First of all, start up the project from modules 3 and 4:

In Postman, Ctrl/Cmd + N → HTTP Request. Type the GET method and the URL:

Press Send. Notice that Postman has understood the query string and filled the Params tab in by itself with one row per parameter: you can enable and disable them with the checkbox, which is the comfortable way to try filter combinations without editing text.

The response our API returns:

The body is the first thing anyone looks at and the least interesting for what we have built. At the bottom of Postman there are three pieces of data that sum up half of module 4:

• Status: 200 OK.
• Time: the total time of the request. Careful: it includes DNS resolution, the connection and TLS, so it will always be higher than the latency prom-client measures at /metrics (04-07). Hover over it to see the breakdown by phase, which is the quickest way to discover that "the API is slow" is really "the TLS handshake takes 300 ms".
• Size: the size. If you enabled compression in 04-06, you will see the compressed size.

The response Headers tab is where module 4's work gets verified:

Four checks worth doing by hand the first time:

1. ETag and 304. Copy the ETag value, create an identical request with the If-None-Match header set to that value and send it. It must answer 304 Not Modified with no body. Postman shows Size: 0 B for the body: that is where you really see the saving from 04-06.
2. Aroma-RateLimit-Remaining. Press Send ten times in a row and watch it go down. It is the simplest check that the limiter from 04-04 is active in this environment.
3. Link. Copy the rel="next" URL into a new request: it must bring you the next page without you having to build the offset yourself. If you have to work it out by hand, HATEOAS is not working.
4. Aroma-Trace-Id. Copy it and search for it in the pino output in your terminal. It must appear on every line for that request. That is the correlation from 04-07 seen from the outside.

Tip. Try an error on purpose too: GET /v1/coffees?roast=purple. It must answer 400 with {"error":{"code":"invalid_parameter",...}} and without a traceId in the body, because only 5xx responses carry one. Seeing the error contract being honoured is as important as seeing the happy path.

A loose request gets lost. The next step is to create the collection. In the left-hand panel: Collections → + and name it Aroma Store v1.

The structure we are going to build reflects the resources of the contract from 02-02, not the implementation:

Three decisions in that structure deserve an explanation:

• The numeric prefix (00, 01, …) is not decoration: the Collection Runner runs requests in the order they appear, and the 00 Sessions folder must run first because it is the one that obtains the token everything else uses.
• One folder per resource, not per use case. Use cases change every quarter; resources are the stable part of the contract.
• The 99 Expected errors folder is what separates a professional collection from a list of requests. It documents the behaviour of the error catalogue from 02-04 and catches the most common regression: someone touches authorisation and a 403 turns into a 500.

These are the central requests exactly as they end up configured. We start with the login, on which everything else depends:

Expected response, 200, with the JWT we issued in 03-06:

Listing with filters, using the Params tab so you can disable them one by one:

Creating a coffee, which requires the administrator role according to the permission matrix from 03-06:

Partial update with merge-patch, the format we settled on in 02-05. It is easy to get this wrong: the Content-Type is not application/json, and our API answers 415 with Accept-Patch if you get it wrong.

And order creation, the only one —along with payment— that requires an Idempotency-Key:

Notice that not a single value is hard-coded: {{baseUrl}}, {{token}}, {{coffeeId}}, {{idempotencyKey}}. That is what the next section is about.

Postman resolves {{name}} by looking through several scopes, from the most specific to the most general. Understanding this hierarchy avoids 80 % of all "but I typed the URL correctly" moments.

Rule of thumb: if the value changes depending on where you point, it belongs to the environment; if it is always the same, it belongs to the collection; if you think it is global, you are almost always wrong. Global variables are the usual cause of "it works on my machine": someone has a value in their installation that is not in the file they shared.

Collection variables for "Aroma Store v1":

The seeded identifiers (cof_001, ord_5001) go in the collection because npm run seed from 03-05 guarantees them in every environment.

An environment is a set of values for the same keys. You switch with the dropdown in the top right corner, and the whole collection points somewhere else without touching a single request.

The local environment file, exportable and safe to version because it contains nothing sensitive:

allowWrites is not a whim. It is the handbrake that prevents the worst possible story with an HTTP client: running the whole collection against production and creating forty test coffees in the real catalogue. In the pre-request script of the write folders:

Postman distinguishes the type of a variable: default (plain text) or secret (shown masked and left out when you export or share the environment).

Rules for Aroma Store:

• The real password of any account, the OAuth client_secret from 04-03 and any token: always secret.
• No token is ever typed by hand. The token is a derived value: the login produces it and a script stores it. If you paste it by hand, it expires in an hour and you paste it again, and so on until someone commits it.
• The production environment's passwords are not stored in the file: they are filled in on the spot, or better still, there is no production environment with write permissions in the shared collection.
• The exported file gets reviewed before it goes into the repository. A quick grep saves you from unpleasant surprises:

Typing Authorization: Bearer {{token}} by hand into thirty requests guarantees that three will end up without it. The Authorization tab exists for exactly that and works by inheritance:

1. On the collection: Auth Type → Bearer Token, Token → {{token}}.
2. On each request: Auth Type → Inherit auth from parent (the default).
3. On the 00 Sessions folder and on the POST /v1/customers sign-up: Auth Type → No Auth, because they are public and sending an expired token to POST /v1/sessions is unnecessary noise.
4. On the administration requests: Bearer Token → {{adminToken}}, overriding the inheritance.

The 99 Expected errors folder deserves attention: the "Create coffee without token → 401" request must be on explicit No Auth, and "Create coffee as customer → 403" on Bearer with {{token}} (Marta's, role customer). If both inherit the same thing, one of the two is not testing what it says it tests.

Postman also supports the full OAuth 2.0 flow from 04-03: under Auth Type → OAuth 2.0 you can configure Authorization Code with PKCE, and Postman opens the browser, performs the exchange and stores the token. It is the correct way to test the CataBox integration, and to really check that a token holding only the coffees.read scope receives 403 insufficient_permissions when it tries POST /v1/orders.

Every request, folder and collection has two JavaScript scripts: Pre-request (before sending) and Post-response (on receipt; in earlier Postman versions it was called "Tests"). They run in cascade: first the collection's, then the folder's and finally the request's.

The most useful pre-request use in our API is renewing the token if it has expired, so the collection works even if you have not touched it for two hours. In the collection's pre-request script:

Points worth understanding about this script:

• pm.sendRequest is asynchronous with a callback. Postman waits for it to finish before sending the main request, but any pm.environment.set you do outside the callback will run too early.
• The one-minute margin avoids the classic race: the token is valid when the script checks and has expired by the time it reaches the server.
• Throwing an Error stops execution with a clear message instead of leaving you investigating why everything returns 401.
• console.log writes to the Postman Console (Ctrl/Cmd + Alt + C), which also shows the exact HTTP request that was sent, headers included. It is the number one debugging tool and almost nobody opens it.

This is where the collection stops being documentation and becomes a test. The API is pm.test(name, fn), and inside you use pm.expect, which is Chai.

Post-response for POST /v1/coffees:

Post-response for GET /v1/coffees, where what gets checked is the shape of the collection and the pagination from 02-06:

And the expected error from folder 99, every bit as important as the happy path:

Chaining is what turns a list of requests into a journey. The technique is always the same: one request stores a value in a variable, the next one consumes it.

In the post-response of POST /v1/coffees:

Now PATCH {{baseUrl}}/coffees/{{coffeeId}} with If-Match: {{coffeeEtag}} works without touching anything, and the later DELETE does too. An important detail: after the PATCH the ETag changes (the version has gone up), so the PATCH post-response must store it again, or the DELETE will get the 412 precondition_failed from 04-06. It is exactly the same mistake a real client would make, and discovering it here is cheap.

This is the full journey the collection runs:

The last request is the one almost everybody forgets: clean up what you created. Without it, every run leaves a new coffee in the database and the collection stops being repeatable.

There is an alternative to the fixed order worth knowing about: postman.setNextRequest('name of the request') lets you jump around in the runner's execution, for example to skip the rest of a folder if the login failed. Use it sparingly: collections with jumps all over the place are unreadable.

POST /v1/orders requires an Idempotency-Key (02-03 and 04-01). If you hard-code it, the second send will return the same response as the first instead of creating a new order, which is precisely what the header promises. And if you change the body while keeping the key, you will get 409 idempotency_key_reused.

Postman has built-in dynamic variables: it is enough to put {{$guid}} as the header value. But it is better to generate it in the pre-request so you can reuse the same value in the retry test:

And a second identical request, "Create order (retry)", which does not regenerate the key and checks the idempotency contract:

Other useful dynamic variables: {{$timestamp}} (Unix seconds), {{$randomInt}}, {{$isoTimestamp}}, {{$randomEmail}}, {{$randomFullName}}. They are handy for creating test customers without email collisions.

Checking property by property soon becomes unmanageable. Postman bundles AJV, so you can validate the whole response against a JSON Schema:

additionalProperties: true is deliberate: if tomorrow we add roastingCountry to the resource, the collection must not break. That is the forwards compatibility rule from 02-07 applied to tests.

Duplicating these schemas by hand is tedious and they drift apart. The right thing is for them to come out of openapi.yaml, and that is exactly what 05-04 will do with contract tests; here it stands as the quick solution, good enough for exploration.

Right-click on the collection → Run collection. The runner executes every request in order and shows a report with the assertions that pass and the ones that do not.

Options that matter:

• Iterations: how many times the whole collection is repeated (with a data file, one per row).
• Delay: milliseconds between requests. With the rate limiting from 04-04 active, a runner with no delay can eat through the quota and cause 429s halfway through the run. 50-100 ms is usually enough.
• Keep variable values: whether the values written by the scripts are persisted. Turn it on while you debug, turn it off to check the collection works from scratch.
• Run manually / Automatically: step-by-step execution is extremely useful for debugging a broken chain.

To test several coffees without duplicating requests, the runner accepts a data file; each row is an iteration and its columns become variables.

postman/coffees-data.csv:

The request body uses the columns as variables, and note the detail about the quotes: {{priceEuros}} goes without quotes because it is a number, and {{name}} with them because it is text.

The expected column lets a single request validate both valid and invalid cases:

This tests the Zod validation from 03-04 and the error format from 03-07 in one go, with five lines of CSV instead of five requests.

Newman is the command-line collection runner. It is the piece that makes everything above useful to somebody other than you.

Export the files first (right-click → Export, format Collection v2.1) into the repository's postman/ folder:

And run it:

The key point for 05-05: Newman returns a non-zero exit code if any assertion fails. That is all a CI pipeline needs in order to block a deployment.

Add it as a script in package.json:

And newman plus newman-reporter-htmlextra go into devDependencies.

There is no need to create the requests by hand if you already have the contract. Import → File → openapi.yaml generates a complete collection with every route, parameter, example body and folders per tag.

Pros and cons, because it is not magic:

• In favour: instant coverage of every endpoint, bodies pre-filled with the specification's example values, and an indirect check that openapi.yaml describes what you think it does.
• Against: it brings no scripts, no chaining and no assertions —the very things that give the collection its value— and re-importing goes badly: Postman creates a new collection instead of merging, and you lose your scripts.

A practical strategy: import once to get the skeleton, add scripts and chaining on top, and maintain the collection by hand from then on. When the contract adds a new endpoint, import it into a temporary collection and copy across the missing request. Real synchronisation between contract and implementation is not solved here: it is solved with the contract tests in 05-04.

Postman generates browsable documentation from the collection: Markdown descriptions of each request and folder, parameters, and automatically generated code samples in curl, JavaScript, Python or Go.

Two habits that multiply its value:

1. Save response examples. On each request, the "Save as Example" button after a good response. Save at least the success case and one error per endpoint. The examples are what shows up in the documentation and, on top of that, what feeds the mock server in the next section.
2. Write a description for each folder explaining which role is needed, what preconditions it has and what errors to expect. It is documentation that lives where it is used.

Ways of sharing, from the least to the most committing: export the JSON and put it in the repository (the one we recommend, because it gets reviewed in pull requests and does not depend on accounts); publish the documentation as a public link; or use team workspaces with cloud synchronisation, which are convenient but mean the contents of your collections live on a third-party server —have security review that before you put an internal API in there.

For external consumers like CataBox, Postman documentation is one option, but the natural destination is the developer portal from 05-06, fed by the openapi.yaml from 05-02.

Postman can spin up a public URL that answers with the saved examples from your collection. It lets the SPA team start laying out the catalogue screen before the endpoint even exists.

It takes three clicks to create and has two important limits: it answers with fixed examples and no logic —the ?roast=light filter does not filter anything— and it depends on Postman's cloud.

It is one option among several, and not the best one if you already have a contract: Prism generates the mock straight from openapi.yaml, with no separate examples to maintain. We will look at it in depth in 05-04, along with msw and nock.

• Writing the full URL in every request. The day a staging environment appears you have to edit forty requests. {{baseUrl}} from the very first one, always.
• Pasting the token by hand. It expires in an hour and you end up with tokens in the exported collection, which is to say in the repository. The token is obtained with the login and stored by a script.
• Exporting the environment with secrets inside. Mark sensitive variables as secret, review the file before committing and add postman/*.local.json to .gitignore.
• Assertions that only check the status. pm.response.to.have.status(200) passes even if the API returns an empty array because the filter was ignored. Check the shape and the content too.
• Forgetting the clean-up. Every run leaves data behind. Finish each folder with a DELETE of whatever it created, or seed the database beforehand with npm run db:reset.
• Confusing environment variables with collection variables. If baseUrl lives in the collection, the environment dropdown does nothing and you always end up pointing at the same place.
• Running the runner with no delay against an environment with rate limiting. Random 429 failures that look like API bugs and are not. --delay-request 100, or a specific quota for the CI client (04-04).
• Content-Type: application/json on the PATCH. Our API answers 415 unsupported_format with Accept-Patch. The correct value is application/merge-patch+json.
• Not opening the Postman Console. That is where you see the literal request that was sent, with the variables already substituted. Most "I don't understand what's happening" moments are solved in ten seconds by looking at it.
• Tip: name requests after what they test, not after the method. "Create coffee as customer → 403" says far more than "POST coffees 2".
• Tip: put the collection in the same repository as the API. That way the pull request that changes an endpoint also changes its request, and review catches the inconsistencies.

Build the 99 Expected errors folder of the "Aroma Store v1" collection with five requests that verify the catalogue from 02-04, and write their assertions. The cases: non-existent coffee (404 coffee_not_found), invalid query parameter (400 invalid_parameter), creation without a token (401 not_authenticated with WWW-Authenticate), creation with the customer role (403 insufficient_permissions) and PUT /v1/coffees (405 method_not_allowed with Allow).

For each one, state which Authorization configuration it needs and write the post-response script for at least three of them.

Create a 10 Purchase journey folder that runs, in order and with no manual intervention: log in as Marta → list coffees (saving the id of the first one with stock available) → create an order with a generated Idempotency-Key → pay the order → fetch the order and check that its status is paid.

Write the scripts you need and explain which variables travel between requests and in which scope you would store them.

Prepare the terminal run of the collection so that it works as a quality gate before a deployment: a data file with at least two valid and two invalid coffee-creation cases, the Newman command that runs it against the test environment injecting the password without writing it into any file, and the package.json script. Explain how the CI system will know whether it should block the deployment.

Authentication configuration per request:

Request 3 — POST {{baseUrl}}/coffees without a token:

Request 4 — POST {{baseUrl}}/coffees with Marta's token (role customer):

Request 5 — PUT {{baseUrl}}/coffees:

Scopes chosen: every variable in the journey goes to pm.collectionVariables, not to pm.environment. The reason: they are ephemeral values from one particular run and must not pollute the environment file that gets shared. The token is the exception: it goes to the environment because every folder shares it and the collection's pre-request manages it.

Request 1 — POST {{baseUrl}}/sessions (No Auth). Post-response:

Request 2 — GET {{baseUrl}}/coffees?available=true&limit=5:

Request 3 — POST {{baseUrl}}/orders. Pre-request:

Body and post-response:

Request 4 — POST {{baseUrl}}/orders/{{orderId}}/payment with Idempotency-Key: {{$guid}}:

Request 5 — GET {{baseUrl}}/orders/{{orderId}}:

Variables that travel: token (environment) → all of them; customerId and coffeeId (collection) → request 3; orderId (collection) → requests 4 and 5; idempotencyKey (collection) → request 3.

File postman/coffees-data.csv:

Post-response covering both cases:

Command with the secret injected from outside:

--env-var overrides the value from the environment file. That way the versioned file can have an empty customerPassword and the real value arrives from an environment variable that in CI comes from the secret manager (05-05), never from the repository.

Script in package.json:

How it blocks the deployment. Newman exits with code 0 if every assertion passes and with a non-zero code if any fails or there is a network error. Any CI system reads a non-zero exit code as a failed step and stops the pipeline. On top of that, the junit report lets the interface show exactly which assertion failed, without having to read the log. If you want the failure to be immediate rather than running the whole collection, add --bail.

You have turned manual exploration into an artefact. The "Aroma Store v1" collection is no longer a list of URLs: it has folders per resource that mirror the contract from 02-02, environments that let you point at local, test or production without editing a single request, a handbrake that stops you writing to production by accident, and a pre-request that renews the token from the 03-06 login before it expires, without anyone pasting credentials by hand.

On top of that base you have added what turns it into a test: assertions that verify the 201 and its Location, the {data, total} shape of collections, that the filters from 02-06 really filter, that the price comes out in euros and not in cents, that the errors from the 02-04 catalogue arrive with their exact code and without a traceId on 4xx responses, and JSON schemas validated with AJV that tolerate new fields. You have chained a complete purchase journey passing the id and the ETag from one request to the next, generated an Idempotency-Key per run to test the retry behaviour from 02-03, and multiplied the cases with a CSV file in which each row declares the code it expects. And with Newman all of that runs from the terminal, with an exit code that is enough to block a deployment: the project's new files are postman/aroma-store-v1.postman_collection.json, postman/local.postman_environment.json, postman/test.postman_environment.json and postman/coffees-data.csv, with newman in devDependencies and the test:api and test:smoke scripts in package.json.

One loose end remains, and it is the important one: the collection is a second description of the API, written by hand, which can drift from the real one without anyone noticing. We already have a better description —the openapi.yaml we have been dragging along since 02-08— but it is half-finished: a single endpoint, no complete schemas, no declared security and unpublished. In 05-02, Swagger and OpenAPI for documentation, we finish it: the full anatomy of the document section by section, components with reusable schemas, parameters and responses, the securitySchemes with the OAuth scopes from 04-03, the difference between writing it by hand and generating it from the code, Swagger UI served at /docs inside the project itself, validation with swagger-cli and the Spectral rules from 04-01, and generating TypeScript clients for the SPA and for Aroma Mobile from the contract.