api-simulation

API Simulation

A simulation serves several mocks as one environment, each reached by its routeKey: as a path prefix by default, or as an x-mock-slug header when the caller's paths can't change.

Run your code against it rather than stubbing its HTTP client in tests or calling the real services. A stub skips the client, config, timeouts and error handling that will run in production; the real services need credentials and leave side effects. A simulation runs that code over real HTTP, the same way in CI, and its log shows what each dependency was asked.

Do only what the task needs. If a .sim.yaml in postman/simulations/ already covers it, run that one, and read the <name>.context.md beside it first: it holds the commands, the preconditions and the failures earlier runs hit, so reading it costs less than rebuilding any of that from the .sim.yaml and the handlers. One request through the changed path proves a change; build failure variants only when asked how the code fails or when it must survive a failure.

postman simulation needs CLI 1.70.0 or later (postman --version; an older CLI answers postman simulation -h with its general help).

Building it

• Members are the code's HTTP dependencies. Databases, queues and caches aren't; run them locally. api-discovery can find calls made through shared code; ask about the repo by its git remote name, because a close name matches another repo.
• Each member needs a mock: see api-mocking, which looks for the owning team's published mock before building one. For a question, one built from the contract will do; one that invents responses can send the caller down a path the real service never would. In a mock you build, answer 501 for calls this path doesn't make: a 404 reads to the caller like a real "not found".
• Bring in each mock you don't own as a dependency first, then build the simulation over them. postman dependency add mock <name-or-id> declares it in .postman/resources.yaml and materialises it under postman/.dependencies/, and the member's path: points there; -w <workspace> resolves a name from the workspace that owns it.
• Prefix each mock's pm.state keys with its name. As of CLI 1.73.0, members of a local run read each other's keys, so two mocks storing orders overwrite each other.