Mock Servers

Analogy categoryAnalogies

What Is a Mock Server?

A Mock Server is a Postman feature that turns a collection's saved request/response examples into a live, callable HTTP endpoint. When a client sends a request that matches a saved example's method and path, the mock server instantly returns that example's stored response — no real backend, database, or business logic needs to exist yet.

🏏

Cricket analogy: A mock server is like a batting net with a bowling machine standing in for a real bowler, letting a batter practice shot timing before facing an actual opponent in the middle.

Creating a Mock Server from a Collection

Creating a mock server from a collection generates a unique, publicly reachable URL in the form https://<mock-id>.mock.pstmn.io. Every request stored in the collection needs at least one saved example (a captured response body, status code, and headers) for the mock to have something to return when a matching request arrives.

🏏

Cricket analogy: Generating a mock server from a collection's saved examples is like a coach building a practice bowling machine's delivery pattern straight from footage of a real fast bowler, so the simulation matches reality.

json

// Saved example on GET /users/1 (used to generate the mock response)
// Request: GET https://{{mockBaseUrl}}/users/1

// Response body Postman returns from the mock server:
{
  "id": 1,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin"
}

Dynamic Responses with Variables and Examples

A single request can hold multiple saved examples — a success case, a validation error, a not-found case — and clients can trigger a specific one by varying query parameters, headers, or the x-mock-response-name header. This lets a mock simulate realistic branching behavior instead of always returning the same canned success response.

🏏

Cricket analogy: Using dynamic variables in a mock's response is like a bowling machine varying its delivery speed and line each time so the batter never faces the exact same ball twice, keeping practice realistic.

Use Cases: Parallel Development and Demos

The most common use of mock servers is letting a frontend team point their app's base-URL variable at the mock and build/test UI flows while the backend team is still implementing the real endpoints. Beyond parallel development, mock servers are also useful for demos, sandboxing third-party integrations, and reproducing edge-case responses (like rate-limit errors) that are hard to trigger against a real system on demand.

🏏

Cricket analogy: Letting the batting coach run drills while the groundskeeper is still preparing the actual pitch is like frontend and backend teams working in parallel against a mock server while the real API is still being built.

A mock server URL looks like https://<mock-id>.mock.pstmn.io — swap your app's base URL environment variable to point at it, and every request that matches a saved example returns that example's response instantly.

Mock servers match requests by method + URL path (and optionally headers/body) against saved examples. If no example matches, Postman returns a 404 with an unmatched-request message — so keep your saved examples in sync as the real API's contract evolves.

A Mock Server serves canned responses based on a collection's saved request/response examples, without needing a real backend.
Creating a mock server generates a unique URL (https://<id>.mock.pstmn.io) that returns the matching example whenever a request's method and path align.
Frontend teams can point their app's base URL at the mock server to build and test UI before the real API is finished.
Dynamic variables and multiple saved examples per request let a mock return different responses for different scenarios (success, error, empty state).
If no saved example matches an incoming request, the mock server responds with a 404 unmatched-request error.
Mock servers are also useful for demos and third-party integration testing when the real API shouldn't be exposed yet.