api-mocking

API Mocking

Overview

A mock is two files on disk: config.yaml (name, port, list of scenarios) and default.js — a plain Node HTTP server, and the mock itself, not a wrapper around one. Because it's just code, generating, inspecting, running, and calling a mock are all local and work for a logged-out guest. Only sharing it — pushing it to the cloud and deploying a durable URL — needs postman login.

Local and cloud aren't a choice made once at generate time. Every mock starts as a local folder; mock push promotes any existing local folder to the cloud later, whether or not -w was passed at generate. Reach for cloud only when something other than you needs to hit this mock over the network — a teammate, a CI job elsewhere, a webhook sender. A purely local mock answering a postman request on your machine never needs it.

Process

1. Generate. postman mock generate -n NAME --port N with no source scaffolds a complete sample cart mock — the fastest way to a server that already answers, useful whenever the point is exercising mock behavior rather than a specific API's shape. Pass a real source — postman mock generate SOURCE -n NAME --port N, where SOURCE is a collection folder or an openapi.yaml — when the endpoints need to mirror an actual API. Either form writes config.yaml + default.js into postman/mocks/NAME/. Adding -w <workspaceId> also creates the mock in that workspace on top of writing the local files — it doesn't replace the local write, and it requires being logged in.
2. Run it. postman mock run ./postman/mocks/NAME starts Mock server started at http://localhost:PORT. If the port in config.yaml is taken and --port wasn't passed explicitly, it falls back to a free OS-assigned port instead of erroring — read the real port off that line rather than assuming the configured one. Naming --port explicitly makes a taken port a hard Port already in use error instead.
3. Call it. Plain postman request localhost:PORT/route returns the default scenario's response. Two headers change that per-request, with no restart needed: x-mock-scenario: <name> selects a different scenario (the valid names live in config.yaml — mock get only ever shows the default one), and x-mock-response-code: <code> returns that status instead. A wrong route and a wrong scenario name both come back as Endpoint not defined — indistinguishable from the message alone. There's no hot reload: a default.js edit does nothing until you Ctrl+C the running server and mock run it again.
4. Push it, if it needs to leave your machine. postman mock push ./postman/mocks/NAME is safe to re-run — Created the first time, Updated after. It returns a cloud ID that is a new identifier, not the id already sitting in config.yaml — see The three identifiers below. It also modifies .postman/resources.yaml; commit that change.
5. Deploy it, for a URL that outlives your terminal. postman mock deploy CLOUD_ID -s SLUG -y --auto-deploy prints https://SLUG.mock.<team-domain>.postman.dev. Deployed private by default — callers need an API key — add --public only when the mock should be reachable by anyone with the URL. -y alone accepts private/auto-deploy-off; without --auto-deploy, a later push doesn't change what's actually being served until you deploy again.
6. See who's calling it. postman mock get CLOUD_ID --json returns .mockServerId; feed that into postman mock log MOCK_SERVER_ID --json for call entries. An empty log means the URL genuinely hasn't been hit — a rejected caller still shows up, recorded with its failing status code.
7. Tear down. postman mock delete ./path --yes (local) or postman mock delete CLOUD_ID --yes (cloud) — both refuse while the thing is still alive, so stop the local run or bring the deployment down first. Cloud delete doesn't touch .postman/resources.yaml; drop that line by hand afterward or the repo keeps claiming a mock that's gone.