Postman Primer

Key Concepts

Workspaces

Workspace Organization

Best practices for workspace organization:

First check to see if the workspace already exists!
Workspaces are currently, and mostly, divided by Bitbucket Projects e.g. Identity User Services or VAMF Data Store
If a new, or more general, workspace is needed then create one and try to use a descriptive name that will help identify the purpose or project
- Document the purpose and contents in the workspace description

Recommended Workspace Access Model

Limited Admin/Editor Access: Restrict Admin and Editor roles to a small group of designated maintainers who are responsible for keeping collections current with service repositories.
Viewer-Based Collaboration: All other team members should have Viewer access to maintain collection integrity.
Fork-Based Workflow: Team members should fork collections when modifications are needed rather than directly editing the source collections.
Pull Request Governance: Changes to official collections should follow a pull request process in Postman, similar to code repositories.
Repository Synchronization: After PR approval, collection updates should be committed to the corresponding service repository to maintain synchronization between code and API documentation.

Collections

What Are Collections?

Collections in Postman are groups of API requests that can be organized, documented, and executed together. They serve as:

Documentation for services
Testing suites for endpoints
Automated workflows through sequenced requests
Shareable specifications for team collaboration

Collections can contain:

Individual requests
Folders and subfolders for organization
Documentation for each endpoint
Test scripts for validation
Pre-request scripts for setup
Variables scoped to the collection

Importing APIs from Swagger/OpenAPI

Postman’s importer is not the best, but it is more practical than adding requests manually

To import a Swagger/OpenAPI definition:

Click "Import" in the upper left corner
Choose file and select swagger.json from a local project
Import as a Postman Collection
Click "Import"

Collection Organization Principles

Folder Structure:

Organize by resource types (e.g., Appointments, Slots, Veteran, Staff)
Use subfolders for complex resource hierarchies
Consider organizing by user flows or test scenarios

Request Order:

Place authentication/setup requests at the beginning
Arrange requests in logical sequence
Group related endpoints together (e.g., CRUD operations for a resource)
- Consider the order needed for collection runs

Variables

Scopes & Usage

Environment Variables:

Tied to a specific environment (e.g., sandbox, staging, prod)
Used for environment-specific values, mostly URLs

Collection Variables:

Scoped to a specific collection
Available to all requests within the collection
Used for collection-specific constants (vistaSite, patientIcn, dfn, etc)
Defined in the collection’s "Variables" tab

Using variables appropriately is essential for creating maintainable, reusable collections that work across environments.

See the Postman documentation on variables and scoping for more details on variable precedence and usage.

Using Variables in Requests

Variables can be used throughout Postman:

To reference a variable, use double curly braces: {{variable_name}}

URLs: {{svc_url}}/users/{{icn}}
Headers: Authorization: Bearer {{access_token}}
Request parameters: ?facilityId={{vistaSite}}
Request bodies: {"patientIcn": "{{icn}}"}
Test scripts: pm.variables.get("variable_name")
Pre-request scripts: pm.variables.set("variable_name", "value")

Dynamic Variables with Scripts

Dynamic variables are created or modified at runtime through scripts:

Pre-request Script Example:

//todo

Post-response Test Script Example:

//todo

Environments

What Are Environments?

Environments are sets of key-value pairs that allow you to customize request execution for different contexts. They enable:

Switching between development, testing, and production servers
Maintaining different authentication credentials per environment
Isolating test data for different scenarios
Configuring environment-specific behaviors

Additional Topics

Forking Collections and Environments

Forking creates a linked copy of a collection or environment that tracks the original. Benefits include:

Making changes without affecting the original
Experimenting with new approaches
Contributing changes back to the original through pull requests
Testing modifications in isolation

To fork a collection:

Open the collection you want to fork
Click the "…" menu and select "Create a fork"
Name your fork and select the destination workspace
Click "Fork Collection"

To fork an environment:

Go to the Environments tab
Click the "…" menu next to the environment
Select "Create a fork"
Name your fork and select the destination workspace
Click "Fork Environment"

Working with forks:

View changes between your fork and the original
Create pull requests to merge changes back
Sync your fork with updates from the original
Manage multiple forks for different purposes

Controlling Collection Runs

How to Skip Folder Run:

To skip a folder during a collection run:

Add a pre-request script to the folder with:

if ('icn' === null) {
    pm.execution.skipRequest();
}

How to Kill the Entire Collection:

To stop a collection run based on a condition:

// In a test script
if (pm.response.code === 401) {
    // Critical failure, stop the collection run
    postman.setNextRequest(null);
}

Test Simplicity

Keeping tests simple:

Focus on smoke tests for basic functionality
Avoid overly complex validations that make tests brittle
Test critical paths rather than every edge case
Use simple assertions for status codes and response format
Consider the purpose: monitoring vs. deep validation