Mock Servers

What is a Mock Server?

A mock server returns pre-defined responses to API requests — without any real backend running. You define what the response should look like, and the mock server returns exactly that.

Why this is useful:

• Frontend-first development — build and test UI components before the API is built
• Parallel development — frontend and backend teams work simultaneously on agreed contracts
• Offline testing — test your app without network access
• Stable test data — return consistent, predictable responses for demos and QA

Creating a Mock Server

You create mock servers from saved examples in your collections. The flow is:

1. Create a collection with requests
2. Add examples to those requests (saved request/response pairs)
3. Create a mock server from the collection
4. Postman generates a URL that returns your example responses

Step 1: Add an Example to a Request

1. Open a request in your collection
2. Send it (or don't — you can create examples manually)
3. Click "Save as example" in the response panel
4. Give it a name (e.g., "Success - 200")

You can create multiple examples per request for different scenarios:

• Success - 200 — normal response
• Not Found - 404 — when resource doesn't exist
• Unauthorized - 401 — when token is missing

Step 2: Create the Mock Server

1. Right-click your collection → "Mock collection" Or go to: Mock Servers in the left sidebar → +
2. Select your collection
3. Choose an environment (optional — for variable substitution)
4. Give it a name
5. Click "Create Mock Server"

Postman gives you a URL like:

https://abc123.mock.pstmn.io

Defining Mock Responses

When you create an example, you define exactly what the mock returns:

Example: GET /users/1 → 200 OK

Request:

GET https://abc123.mock.pstmn.io/users/1

Example response body:

{
  "id": 1,
  "name": "Rizwan Ashiq",
  "email": "rizwan@example.com",
  "role": "admin",
  "createdAt": "2024-01-15T10:30:00Z"
}

Example response headers:

Content-Type: application/json
X-Request-Id: abc-123

Status code: 200 OK

Save the example and the mock server will return this exact response whenever GET /users/1 is called.

Matching Requests to Examples

Postman matches incoming mock requests to examples based on:

1. Request URL path (required match)
2. HTTP method (required match)
3. Query parameters (optional — for more specific matching)
4. Request headers (optional)
5. Request body (optional)

If multiple examples match, Postman uses the most specific one. If nothing matches, it returns a 404.

Using Query Parameters for Different Responses

Create two examples for the same endpoint with different query params:

Example 1: GET /products?category=electronics  → electronics list
Example 2: GET /products?category=books        → books list
Example 3: GET /products                       → all products

The mock server returns the matching example based on the query parameter.

Dynamic Responses with Variables

Use Postman variables in example responses for dynamic values:

{
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "randomNumber": {{$randomInt}},
  "userName": "user_{{$randomUserName}}"
}

Built-in dynamic variables:

Variable	Returns
{{$guid}}	Random UUID
{{$timestamp}}	Current Unix timestamp
{{$randomInt}}	Random integer (0–1000)
{{$randomFirstName}}	Random first name
{{$randomEmail}}	Random email address
{{$randomUserName}}	Random username
{{$randomPhoneNumber}}	Random phone number

Simulating Error Responses

Add examples for error scenarios to test how your frontend handles them:

401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Authentication token is missing or invalid"
}

422 Validation Error:

{
  "error": "Validation failed",
  "details": [
    { "field": "email", "message": "Must be a valid email address" },
    { "field": "password", "message": "Must be at least 8 characters" }
  ]
}

500 Server Error:

{
  "error": "Internal Server Error",
  "message": "Something went wrong on our end"
}

Now your frontend can handle all these cases before a real backend is built.

Using the Mock URL in Your App

Point your frontend's API base URL to the mock server during development:

.env.development

REACT_APP_API_URL=https://abc123.mock.pstmn.io

.env.production

REACT_APP_API_URL=https://api.yourapp.com

Your frontend code doesn't change — just the environment variable. Switch to the real API when it's ready.

Sharing Mocks with Your Team

Mock servers are tied to your Postman workspace. Team members in the same workspace can use the same mock URL — great for frontend devs who need a consistent API to build against while backend is in development.

To share:

1. Make sure the collection is in a shared workspace (not personal)
2. Share the mock URL with your team
3. Team members use it directly in their .env files or Postman requests

Add the mock URL to your environment

Store the mock URL as an environment variable in Postman:

MOCK_URL = https://abc123.mock.pstmn.io

Then toggle between MOCK_URL and BASE_URL environments when switching between mock and real API testing.