postman

Build Postman collections and environments, write request scripts, and run API smoke checks with Newman.

SKILL.md

GitHub

Postman API Collections AI Skill Guide

Overview & Engine Architecture

Postman organizes HTTP requests into collections with folders, environments (variables), and optional tests/pre-request scripts. Team workspaces sync shared collections; Newman runs collections in CI. Agents keep secrets in environments - not hard-coded in requests - write assertions that catch contract breaks, and prefer versioned collection exports in git when teams treat APIs as code.

Workspace
   -> Collections (folders / requests)
       -> Environments (local / ci / prod vars)
       -> Tests + pre-request scripts
Newman / Collection Runner -> CI reports

When to use this skill

  • Building shareable API smoke suites
  • Documenting auth flows for other engineers
  • Running Newman in PR pipelines
  • Contrasting with @bruno git-native collections

Operational directives

  1. Never store production tokens in shared collection JSON; use environment secrets / vault injection.
  2. Name requests by intent (POST /orders - create); keep examples minimal and current.
  3. Assert status codes and critical JSON paths; avoid over-fitting to volatile fields (timestamps).
  4. Parameterize base URLs via {{baseUrl}} per environment.
  5. Export/collection sync should not overwrite teammates' in-progress edits without coordination.

Test script sketch

pm.test("status 200", () => pm.response.to.have.status(200));
pm.test("has id", () => {
  const json = pm.response.json();
  pm.expect(json).to.have.property("id");
  pm.environment.set("lastOrderId", json.id);
});

Newman CI sketch

newman run collection.json -e ci.environment.json \
  --env-var "baseUrl=$BASE_URL" \
  --env-var "token=$API_TOKEN" \
  --reporters cli,junit --reporter-junit-export newman.xml

Collection hygiene

Smell Better approach
Prod password in collection Environment secret / CI variable
One giant unsorted dump Folders by resource; happy-path + negative cases
Tests only check status !== 500 Assert schema-critical fields
Duplicated auth on every request Collection auth or pre-request token refresh

Best practices

  • Keep a "smoke" collection small enough for every PR; deeper suites nightly.
  • Document required env vars in the collection description.
  • For git-first workflows with PR review of requests, also consider @bruno.
  • Rotate tokens used in shared team environments regularly.

Limitations

  • Postman Cloud vs local-only workflows differ on sync, forks, and governance.
  • GraphQL and gRPC support exist but patterns differ from plain REST collections.
  • Contract testing at scale may need OpenAPI-driven tools beyond Postman.

Related skills

  • @bruno - file-based collections complementary to Postman
  • @openapi-endpoint-filtering - shrink large specs before client gen
  • @playwright - full UI flows when API smoke is not enough