Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

08.06 Using the Postman Collection

SimpleRisk's OpenAPI specification (rendered in Swagger UI) imports cleanly into Postman as a collection. Set the API key once at the collection level; every endpoint gets the X-API-KEY header automatically. Use Postman's environments to switch between dev, staging, and production instances.

Why this matters

Postman is the de facto API exploration and testing tool for many developers. Where the in-product Swagger UI is convenient for browsing and quick try-it-out, Postman adds: persistent collections of saved requests, environments for switching between dev / staging / production, scripting via pre-request and test scripts, automation via Newman (Postman's CLI runner) for CI integration, team collaboration via shared workspaces.

For programs whose integration developers prefer Postman, the path is to import the SimpleRisk OpenAPI spec as a Postman collection and work from there. This article covers the workflow.

Before you start

Have these in hand:

  • Postman installed (desktop app or web — both work; the desktop app has fewer cross-origin restrictions for local development).
  • Access to your SimpleRisk install's OpenAPI spec (typically at /api/v2/documentation/openapi.json or downloaded via Swagger UI's export option).
  • An API key for an integration user with appropriate permissions for what you'll test. See Authentication and API Keys.
  • A non-production SimpleRisk instance for testing destructive operations.

Step-by-step

1. Get the OpenAPI specification

Two paths:

Option A: Download from Swagger UI.

  1. Open /api/v2/documentation.php in your browser.
  2. Look for the spec URL near the top of the page (typically labeled /api/v2/documentation/openapi.json or similar).
  3. Open that URL directly in your browser; the JSON loads.
  4. Save the JSON to a local file.

Option B: Use the URL directly in Postman's import.

If your Postman has network access to your SimpleRisk install, you can import directly via URL without downloading.

2. Import into Postman

In Postman:

  1. Click Import (top-left or via the File menu).
  2. Choose File (if you downloaded) or Link (if importing via URL).
  3. For File: drag the OpenAPI JSON file or pick it via the file browser.
  4. For Link: paste the spec URL.
  5. Postman parses the spec and offers to create a collection. Confirm.
  6. The new collection appears in your collections list, organized by tag (Risks, Governance, etc.) matching the Swagger UI's grouping.

Each endpoint becomes a Postman request with parameters, request body schema, and response examples populated from the OpenAPI definitions.

3. Configure authentication at the collection level

Setting the API key per request is tedious; configure it once at the collection level:

  1. Open the imported collection in Postman.
  2. Go to the Authorization tab.
  3. Set Type to API Key.
  4. Key: X-API-KEY.
  5. Value: your API key (or use a Postman variable like so the actual value lives in an environment).
  6. Add to: Header.
  7. Save.

Now every request in the collection inherits the auth setting; individual requests don't need their own auth configuration unless they need to override.

4. Set up environments for multi-instance work

Most teams have multiple SimpleRisk instances (dev, staging, production). Use Postman environments to switch between them:

  1. Create environment: top-right environment dropdown → Manage Environments → Add.
  2. Name it (e.g., "SimpleRisk Dev", "SimpleRisk Production").
  3. Add variables: - base_url → e.g., https://simplerisk-dev.internal.example.com or https://simplerisk.example.com. - api_key → the API key for that environment (different keys per environment, hopefully).
  4. Save.

In the imported collection, the request URLs use the OpenAPI server URL by default. Edit them to use /api/v2/... so they pick up the environment's variable. The collection-level auth uses similarly.

Switch environments via the top-right dropdown; every request in the collection now hits the selected environment's instance with the correct credentials.

5. Test endpoints

For each endpoint:

  1. Open the request in the collection.
  2. Fill in path parameters (e.g., the {id} in /risks/{id} becomes a request-level variable).
  3. Fill in query parameters as appropriate.
  4. For POST/PATCH endpoints, populate the request body. The OpenAPI import populates a default body shape; replace placeholder values with real data.
  5. Click Send.
  6. The response appears below: status, headers, body, response time, size.

Postman saves the last response per request; you can review history, compare responses, and export examples.

6. Use Postman's testing features

For more rigorous integration development, Postman supports:

  • Pre-request scripts: JavaScript that runs before the request — set dynamic timestamps, generate random IDs, fetch a fresh auth token.
  • Tests: JavaScript that runs after the response — assert on status code, response body shape, specific field values. Tests show pass/fail in the response panel.
  • Collection runner: run all requests in a collection in sequence, with iteration data from a CSV. Useful for bulk operations or load-style smoke tests.
  • Newman: Postman's CLI tool. Run a collection from the command line; integrate into CI pipelines.

For programs building integrations as collaborative work, the test-and-runner features make Postman a useful integration validation surface alongside the actual integration code.

7. Share collections with the team

Postman supports workspace-based collection sharing:

  • Personal workspace: only you see the collection.
  • Team workspace: members of your team see and edit shared collections.
  • Public workspace: anyone with the link can see (use carefully — don't share workspaces containing real API keys).

For team integration development, share the collection in a team workspace. Don't include real API keys in the shared variables; use Postman's environment-variable-with-secret-flag feature (or each developer maintains their own environment with their own key).

8. Re-import after SimpleRisk upgrades

When SimpleRisk upgrades and adds new endpoints, the existing Postman collection won't reflect them. Either:

  • Re-import the spec: Postman will offer to update the existing collection or create a new one.
  • Manually add endpoints: for one or two new endpoints, manual addition is faster than re-import.

If you've customized the imported collection (added scripts, organized differently, etc.), re-import as a new collection and merge changes manually. Postman doesn't have a merge feature.

Common patterns

Pattern A: Quick endpoint validation

You're developing an integration and want to verify an endpoint's behavior with specific parameters.

  1. Open the endpoint in the imported collection.
  2. Fill in the parameters.
  3. Send.
  4. Inspect the response.
  5. Iterate.

Faster than writing throwaway curl commands; faster than coding the integration just to test the call.

Pattern B: Pre-built request library for support

The support team uses Postman to investigate customer issues. They share a collection of common diagnostic requests; investigators run them against the affected install.

Pattern C: Smoke tests via Newman

A CI job runs Newman against the staging SimpleRisk after deployment. The collection contains representative requests with tests scripts asserting the responses are well-formed; failed assertions fail the CI job.

Common pitfalls

A handful of patterns recur with the Postman workflow.

  • Hardcoding the API key in the imported collection. Use environment variables; environments per instance.

  • Sharing collections with embedded API keys. Anyone with the collection has the keys. Use environment variables and don't share environments.

  • Running mutating requests against production from Postman. It's the live API; your test creates / modifies / deletes real data. Use a non-production environment.

  • Not updating the collection after SimpleRisk upgrades. New endpoints don't appear; you might miss capabilities. Re-import periodically.

  • Treating Postman as the integration platform. It's an exploration and testing tool. The actual integration runs in your application code; Postman is for development and validation.

  • Confusing the OpenAPI spec's servers block with the runtime URL. The spec lists example server URLs; replace them with your actual instance URL via .

  • Not version-pinning the imported collection. A collection imported from version X may not match the API of version Y. Note the version somewhere in the collection name or description.

  • Using Postman's web client for development against a non-public SimpleRisk instance. The web client makes requests from Postman's servers, which can't reach your internal-network SimpleRisk. Use the desktop client.

  • Storing test data in the collection that includes sensitive content. Collections get shared, copied, and exported; sensitive data leaks. Use synthetic test data.

  • Forgetting that pre-request and test scripts run JavaScript with full Postman access. Be cautious about importing collections from untrusted sources; the scripts can do almost anything.

Related

Reference

  • Tool: Postman (https://www.postman.com/). Desktop app recommended for non-public-internet SimpleRisk instances.
  • Spec source: /api/v2/documentation/openapi.json (path varies by install) — same OpenAPI spec the in-product Swagger UI consumes.
  • Import method: Postman's Import → File (downloaded JSON) or Link (URL).
  • Authentication: Configure at collection level: API Key type, header X-API-KEY, value via environment variable.
  • Multi-instance setup: Use Postman environments with base_url and api_key variables; switch via the top-right dropdown.
  • CLI runner: Newman (https://www.npmjs.com/package/newman) for command-line execution and CI integration.
  • External dependencies: Postman application; network reachability to your SimpleRisk instance.