Collections, variables and environments

What you will be able to do

Use one collection for every place where the API runs: on your computer now, and on the internet after Module 7. You switch with one menu, and the API key that you add later never leaves your computer.

Before you startWhat to know and to have readyAbout 40 minutes

What you need to know

• The collection variable baseUrl, from First requests in Postman: Make the imported requests work.
• The DNS step, from Browser-to-server basics: From a name to a server: DNS.

What you need on your computer

• The Postman desktop app, signed in, from First requests in Postman: Install the app and sign in.
• The Ticket Classifier API collection, with baseUrl set to http://127.0.0.1:8000. You made it in First requests in Postman: Import the OpenAPI document. If it is missing, import it again as in that section.
• The three failure requests in the collection, from First requests in Postman: Your turn: requests for every row.
• The API runs locally with fastapi dev, as in Environment and first endpoint: Step 3: start the server.
• If your project is missing or broken, copy the snapshot end-of-m04, the project at the end of Module 4, as in Use a snapshot. Then do the guided practice and the “Your turn” task of First requests in Postman again.

The steps for the app follow Postman’s documentation for Postman 12.

Variables

A variable is a name, written {{name}}, that Postman replaces with a value just before it sends a request. You can use variables in the URL, the headers and the body. With variables, the same request works for different servers and different keys, without a change to the request.

Postman keeps variables at several levels, called scopes. This course uses two:

Scope	Belongs to	Use it for
Collection variable	One collection, for every environment	Values that are the same everywhere, or a default
Postman environment variable	One environment, such as “Local” or “Deployed”	Values that change with the place where the API runs: baseUrl, apiKey

A Postman environment is a named set of variables, for example Local with baseUrl = http://127.0.0.1:8000. One environment is active at a time. (This is a different thing from an environment variable in the terminal, and from Python’s virtual environment. This course always writes “Postman environment” for this one.)

If an environment and the collection both have a variable with the same name, the environment wins. Postman shows the collection’s value with a line through it.

The request stays the same. The active Postman environment decides where it goes and which key it carries.

Text description of the diagram

The request in the collection is POST {{baseUrl}}/v1/classify, with the header X-API-Key: {{apiKey}}. The collection has its own baseUrl, http://127.0.0.1:8000. The active Postman environment, Deployed, also has baseUrl, set to https://ticket-api.example.dev, and it overrides the collection’s value. It also has apiKey, marked sensitive, with a local value only. Postman replaces both variables, and sends POST https://ticket-api.example.dev/v1/classify with the real key in the header.

Local values and shared values

Postman keeps your collections and environments in your Postman account, in the cloud, so that you can use them on another computer. Each variable has two values:

Value	Synced to Postman’s cloud?	Use it for
Shared value	Yes. Anyone you share the collection or environment with can see it.	Values that are safe to share: URLs, example IDs
Local value	No. It stays on this computer.	Secrets: API keys, tokens, passwords

Postman sends the local value if there is one. For a secret, leave the shared value empty, and put the real value only in the local value. Also mark the variable as sensitive (the lock icon next to its name). Postman then hides the value on the screen, as ••••. So it does not appear in a screenshot or a screen share.

Worked example: two Postman environments

Amira makes an environment for her computer, and one for the deployed API that she builds in Module 7:

1. In the sidebar, select Environments, then the + (add) icon. Name the new environment Local.
2. Add a variable baseUrl, with the value http://127.0.0.1:8000.
3. Add a variable apiKey. Leave its shared value empty. Mark it as sensitive with the lock icon. (Module 6 gives it a local value.)
4. Make a second environment, Deployed, with the same two variables. For baseUrl, use https://ticket-api.example.dev for now. Module 7 gives you the real URL.
5. In the environment selector at the top right of the window, choose Local.

Now she makes the collection use apiKey in every request, once, at the collection level:

1. Select the collection, and open its Authorization tab.
2. Set Auth Type to API Key.
3. Set Key to X-API-Key, Value to {{apiKey}}, and Add to to Header.
4. Save the collection.

Each request in the collection has the auth type Inherit auth from parent by default, so all of them now send the header. The API ignores it for now. Module 6 makes it required.

She sends Classify a support ticket. In the URL, she holds the pointer over {{baseUrl}}: Postman shows the value from Local, and the collection’s value with a line through it. Then she chooses Deployed in the selector, and sends it again. It fails with an error that the host cannot be found. That is correct: ticket-api.example.dev does not exist. The same request went to a different place, and nothing in the request changed.

Save examples for other developers

A collection is also documentation. Each request can keep examples: saved pairs of a request and its response. The import made examples from your OpenAPI document. You can add real ones:

1. Send Reject an empty subject.
2. In the response pane, select Save Response, then Save as example.
3. Give the example a clear name, such as 422 - empty subject.

A developer who opens the collection sees the exact response for each case, without sending anything.

Guided practice: environments for your collection

1. Make the Postman environments Local and Deployed, as in the worked example, and choose Local.
2. In the collection’s Variables tab, look at baseUrl. Then hold the pointer over {{baseUrl}} in a request, and see that the environment’s value wins.
3. Set the collection’s Authorization to the API key, as in the worked example.
4. Send each request in the collection with Local. All of them give the status code that your contract table says.
5. Choose Deployed, and send Check that the service runs. Read the error, and say at which step of Browser-to-server basics it failed.
6. Choose Local again. Save one example for the success case and one for a failure case.

Show the answer for step 5

It fails at DNS, the first step: the host ticket-api.example.dev does not exist, so there is no IP address to connect to. There is no status code, because no server answered.

Your turn: a third environment

Start a second copy of your API on another port, in a new terminal: fastapi dev ticket_api/main.py --port 8001. Make a Postman environment Local 8001 for it, and send the requests to both copies, by switching environments only. Then stop the second copy.

Which variable did you change, and which requests did you change?

Show the answer

Only one value: baseUrl = http://127.0.0.1:8001 in the new environment. No request changed. That is the point of variables: the requests describe what to send, and the environment says where.

Common mistake

A real API key in a shared value

Symptom: you share the collection or the environment with a teammate, or export it, and the file or their Postman shows your real API key.

Cause: the key was in the shared value of the variable, or directly in a header of a request. Shared values are synced to Postman’s cloud, and included when you share or export. The key has left your computer.

Fix:

1. Treat the key as leaked: cancel it, and make a new one, as in Configuration and secrets.
2. Put the new key only in the local value of apiKey, with an empty shared value, and mark the variable as sensitive.
3. Use {{apiKey}} in the collection’s Authorization, never the key itself in a request.

Check your understanding

The collection has baseUrl = http://127.0.0.1:8000, and the active Postman environment has baseUrl = http://127.0.0.1:8001. Where does a request with {{baseUrl}} go?

Show the answer

To http://127.0.0.1:8001. An environment variable overrides a collection variable with the same name. Postman shows the collection’s value with a line through it. If you choose no environment, the request uses the collection’s value, port 8000.

Check your understanding

Why does apiKey have an empty shared value and a real local value, instead of the other way round?

Show the answer

Shared values are synced to Postman’s cloud and included when you share or export the collection or environment. Local values stay on your computer. A secret must never leave your computer, so it goes only in the local value. The empty shared value still documents that the variable exists, so a teammate knows to set their own key.

Recap

• {{name}} is a variable. Postman replaces it before it sends the request.
• A Postman environment is a named set of variables. Its values override the collection’s.
• Keep the URL in baseUrl per environment, so the same requests work locally and when deployed.
• Secrets go only in the local value, with an empty shared value, marked as sensitive.
• Set the API key once, in the collection’s Authorization. Requests inherit it.
• Saved examples show other developers the exact responses.

Next, you add tests to every request, and run the whole collection from the terminal.

Next: Tests and repeatable runs