Postman’s variable system is actually a powerful, albeit quirky, way to manage API versions.
Let’s see this in action. Imagine you have two versions of an API, v1 and v2, and you want to test them side-by-side.
Here’s a sample Postman collection structure:
{
"info": {
"_postman_id": "...",
"name": "My API Versions",
"schema": "..."
},
"item": [
{
"name": "v1",
"item": [
{
"name": "Get User",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{api_url}}/users/123",
"host": [
"{{api_url}}"
],
"path": [
"users",
"123"
]
},
"description": "Fetches user details for v1"
},
"response": []
}
]
},
{
"name": "v2",
"item": [
{
"name": "Get User",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{api_url}}/users/123",
"host": [
"{{api_url}}"
],
"path": [
"users",
"123"
]
},
"description": "Fetches user details for v2"
},
"response": []
}
]
}
]
}
The core problem this solves is enabling parallel testing and regression checks across different API versions without maintaining entirely separate collections or manually changing URLs. It’s about managing the endpoint definition itself as a variable.
The magic happens with Postman’s environment variables. You create an environment (or use the current one) and define a variable, say api_url.
For your v1 tests, you’d set api_url to http://localhost:3000/api/v1.
For your v2 tests, you’d set api_url to http://localhost:3000/api/v2.
You can then switch between these environments to target different API versions.
The {{api_url}} placeholder in the request URL is dynamically replaced by Postman with the value of api_url from the currently active environment. This means the same request definition can hit different API versions just by changing the environment.
This approach is incredibly flexible. You can:
-
Run Regression Tests: Define tests for older versions and run them against newer versions to ensure backward compatibility.
-
Staged Rollouts: Test a new version in parallel with the old one, using different environments to target each.
-
Feature Flags: If your API uses versioning via query parameters or headers, you can use variables for those too. For example,
{{api_version_header_value}}could be set tov1orv2depending on the environment.
Here’s how you’d set up the environments:
Environment: v1 Testing
api_url:http://localhost:3000/api/v1
Environment: v2 Testing
api_url:http://localhost:3000/api/v2
With these environments, you can select v1 Testing from the top-right dropdown in Postman and run your collection. Then, switch to v2 Testing and run it again. The requests will automatically target the correct base path.
A subtle but powerful aspect is how Postman resolves variables. It looks for them in the following order: global, environment, data (from CSV/JSON), local (within a script). This means you can override environment variables with local variables set in a Pre-request Script for even finer-grained control within a single run, though for managing distinct versions, environments are the cleaner solution.
The next logical step is to automate this version switching and comparison, perhaps using the Postman Collection Runner and scripting to iterate through environments.