api-mocking

API Mocking

A mock is a folder, config.yaml plus a handler such as default.js, that answers like an API. The handler is a Node HTTP server that calls listen(process.env.PORT). It loads as CommonJS even in an ESM project, so import fails: use require. The same mock lives in your repo (postman/mocks/<name>/, run with postman mock run, no sign-in needed), in a Postman workspace after postman mock push, where other teams pull it from, and on a mock server after postman mock deploy, for callers that can't run it themselves.

Several APIs at once, for a service, a frontend or a test suite? Use api-simulation, which gets each member's mock here.

Use the owner's mock first

When the API belongs to another team, look for their published mock before writing one: theirs encodes their contract and their service's state; yours encodes a guess. It needs postman login; signed out, build one and say the owner search was skipped.

1. Find the owner's workspace with postman search workspaces "<service>" -o json. Name the service plainly, as your code does, not by what it returns: a description matches lookalike services. Prefer a Git-connected workspace (isGitConnected) named for that service.
2. List its mocks with postman mock list -w <workspaceId> --json. postman search mocks misses some, and its classicMock results only replay a collection's saved examples: postman mock can't pull or run them, so call one at https://<mockId>.mock.pstmn.io with postman request, or generate a code mock from its collection. A same-named mock in another workspace isn't the owner's.
3. Pull it with postman dependency add mock <mockId> and use it as it is. Never edit postman/.dependencies/: dependency update overwrites it, so copy a mock to postman/mocks/ to change it. A pulled copy loses interceptRequests, so fork one whose handler reads req.body or relies on sessions. A mock is code that runs as you; pull only from workspaces you trust.