Update to Postman

{
  "description": "Finds, builds, runs and publishes a stand-in for one API — the owning team's published mock when there is one, otherwise one built from its spec or collection that behaves like the real API, stateful when callers write then read. Use when something needs an API that isn't built or reachable yet (a frontend, client or demo), when other teams should build against your API before it ships, or when asked to mock an API or fake a backend. To run and test your own code against the services it calls, use api-simulation. Covers `postman mock` and `postman dependency add mock`.",
  "included_files": [],
  "name": "api-mocking",
  "skill_md_contents": "---\nname: api-mocking\ndescription: Finds, builds, runs and publishes a stand-in for one API — the owning team's published mock when there is one, otherwise one built from its spec or collection that behaves like the real API, stateful when callers write then read. Use when something needs an API that isn't built or reachable yet (a frontend, client or demo), when other teams should build against your API before it ships, or when asked to mock an API or fake a backend. To run and test your own code against the services it calls, use api-simulation. Covers `postman mock` and `postman dependency add mock`.\n---\n\n# API Mocking\n\nA mock is a folder, `config.yaml` plus a handler such as `default.js`, that\nanswers like an API. The handler is a Node HTTP server that calls\n`listen(process.env.PORT)`. It loads as CommonJS even in an ESM project, so\n`import` fails: use `require`. The same mock lives in your repo\n(`postman/mocks/<name>/`, run with `postman mock run`, no sign-in needed),\nin a Postman workspace after `postman mock push`, where other teams pull it\nfrom, and on a mock server after `postman mock deploy`, for callers that\ncan't run it themselves.\n\nSeveral APIs at once, for a service, a frontend or a test suite? Use\n`api-simulation`, which gets each member's mock here.\n\n## Use the owner's mock first\n\nWhen the API belongs to another team, look for their published mock before\nwriting one: theirs encodes their contract and their service's state; yours\nencodes a guess.\n\nEvery step below needs a signed-in CLI. Check `postman status` first; signed\nout, skip to building one and say the owner search was skipped.\n\n1. Find the owner's workspace with `postman search workspaces \"<service>\" -o json`.\n   Name the service plainly, as your code does, not by what it returns: a\n   description matches lookalike services. Prefer a Git-connected workspace\n   (`isGitConnected`) named for that service.\n2. List its mocks with `postman mock list -w <workspaceId> --json`.\n   `postman search mocks` misses some, and its `classicMock` results only\n   replay a collection's saved examples: `postman mock` can't pull or run\n   them, so call one at `https://<mockId>.mock.pstmn.io` with\n   `postman request`, or generate a code mock from its collection. A\n   same-named mock in another workspace isn't the owner's.\n3. Pull it with `postman dependency add mock <mockId>` and use it as it is.\n   Never edit `postman/.dependencies/`: `dependency update` overwrites it,\n   so copy a mock to `postman/mocks/` to change it. A pulled copy loses\n   `interceptRequests`, so fork one whose handler reads `req.body` or relies\n   on sessions. A mock is code that runs as you; pull only from workspaces\n   you trust.\n\n## Or build one that behaves like the real API\n\nCallers shouldn't be able to tell the difference on the paths they use. A\nmock that returns invented JSON passes your tests and fails against the\nreal service.\n\n- **Start from the contract.** `postman mock generate <spec or collection>`\n  writes each documented response. It's a replay: a `POST` and a later\n  `GET` share nothing, and it accepts any request, so a call that breaks the\n  contract still gets its answer. `x-mock-response-code` picks only a\n  documented status; any other code gets the default 200, so put the errors\n  callers handle (the unknown-id 404, the conflict 409, the bad-input 400) in\n  the contract. From a spec\n  it serves the server URL's base path (`/v2/...`); from a collection,\n  routes start after the base-URL variable. `--update` regenerates the\n  handler and overwrites your edits. With no contract, write it from how\n  your code calls the API and say what you assumed.\n- **Set `interceptRequests: true` in `config.yaml`.** Without it `req.body`\n  and `req.query` are undefined, `x-mock-session` is ignored, and a throw in\n  an async handler kills the mock instead of returning a `500`.\n- **Make it stateful when callers write then read.** Keep records in\n  `pm.state`, seed them on first use, add a reset route so a test can start\n  clean, and answer an unknown id with the real 404. Every `mock run` starts\n  empty.\n- **Know who shares state.** Locally, all callers share one state unless\n  each sends `x-mock-session: <id>`. A mock server deployed from the CLI\n  isolates each caller: one that keeps neither the same `x-mock-session` nor\n  the `pm_mock_session` cookie starts from the seed on every request, so its\n  `POST` and later `GET` never meet.\n- **Scenarios** are named handlers in `config.yaml`'s `scenarios` list, picked\n  per request with `x-mock-scenario: <name>`. An unknown name falls back to\n  the default locally but is a `404` on a mock server.\n\n## Check it against the contract\n\n`postman mock run` prints the URL it bound; a busy configured port moves\nunless you pass `--port`, so take the URL from that line. Nothing reloads:\nrestart it after an edit.\n\nA mock checked against the handler you just wrote proves nothing, so call\nit with requests from the contract: `postman request`, or the API's\ncollection with\n`postman collection run <collection> --use-mock \"{{baseUrl}} mock:postman/mocks/<name>\"`\n(`--mock` alone only starts it). That form replaces the variable's whole\nvalue, base path included, so a mock generated from a spec that serves\n`/v2/...` answers `404`; start that one with `--mock <path> --port <n>` and\npass `--env-var \"baseUrl=http://localhost:<n>/v2\"`. To check your own calls\nagainst a contract, compare each one, from the code or a simulation log,\nwith the spec; the mock won't reject a wrong one.\n\n## Publish it for other teams\n\n- **Push it to the service's own workspace,** the one this repo is linked\n  to or the one the user names, never one chosen by name match: other\n  teams' simulations look there. Signed out, the push fails but the local\n  mock still works; build it, say so and ask the user to sign in. Keep it\n  honest: change the mock in the same PR as the API and run the API's\n  collection against it.\n- **Deploy only when a caller needs a URL.** The server takes a slug of 3–32\n  lowercase letters, digits and single hyphens, starting and ending with a\n  letter or digit; the CLI accepts more, and its default can be too long.\n  It's private: callers send an API key as `x-api-key`, or, if they can\n  view the workspace, an access token as `x-access-token`. Deploying needs a paid plan; a team's first\n  server can take minutes to answer, and teams that review deploys hold them\n  for approval. Each later `push` changes what every caller of the server\n  gets, so treat it as a release, not a backup.\n- **Write it for where it runs.** A mock server runs each scenario as one\n  file with Node's built-ins, not `fs` or `child_process`: no local\n  `require`s, no `pm.mock` examples, no environment, no console output, and\n  no caller `authorization`, `cookie` or `x-api-key` headers. A mock that\n  relies on any of these works locally and breaks once deployed.\n- **Ask before `--public`.** It serves the mock and its data to anyone with\n  the URL, and a scripted redeploy can't make it private again.\n\n## Before you say it's done\n\nA mock isn't done because it started. Call it: a documented error comes\nback, a valid scenario changes the response, a `POST` then `GET` shows state\nif it should. Say where it runs and who can call it, where it lives, and\nwhat you assumed.\n"
}