Postman Mock Servers let you prototype and test API integrations without needing a live backend.
Let’s see one in action. Imagine you’re building a client application that needs to fetch user data from an API. You want to test how your client handles different user responses, like a user being found or not found, before the actual user API is even ready.
Here’s a Postman collection with a mock server set up for this scenario:
{
"info": {
"_postman_id": "your-collection-id",
"name": "User API Mock",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Get User by ID",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{mock_server_url}}/users/{{userId}}",
"host": [
"{{mock_server_url}}"
],
"path": [
"users",
"{{userId}}"
],
"variable": [
{
"key": "userId",
"value": "123"
}
]
}
},
"response": [
{
"name": "User Found",
"originalRequest": {
"method": "GET",
"header": [],
"url": {
"raw": "{{mock_server_url}}/users/123",
"host": [
"{{mock_server_url}}"
],
"path": [
"users",
"123"
]
}
},
"status": "200 OK",
"code": 200,
"responseTime": 100,
"content": "{\n \"id\": 123,\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n}"
},
{
"name": "User Not Found",
"originalRequest": {
"method": "GET",
"header": [],
"url": {
"raw": "{{mock_server_url}}/users/999",
"host": [
"{{mock_server_url}}"
],
"path": [
"users",
"999"
]
}
},
"status": "404 Not Found",
"code": 404,
"responseTime": 50,
"content": "{\n \"error\": \"User not found\"\n}"
}
]
}
],
"variable": [
{
"key": "mock_server_url",
"value": "http://localhost:5000"
}
]
}
In this collection, we’ve defined a single request, "Get User by ID." Crucially, it has multiple responses associated with it. When you create a mock server from this collection, Postman will listen on http://localhost:5000 (or whatever port you configure).
When your client application makes a GET request to http://localhost:5000/users/123, Postman checks the responses defined for the "Get User by ID" request. It sees that the originalRequest URL in the "User Found" response matches the incoming request’s path and method. So, it returns the "200 OK" status and the JSON content defined for that response.
If the client requests http://localhost:5000/users/999, Postman again looks for a matching response. It finds the "User Not Found" response, whose originalRequest URL also matches the incoming request. It then returns the "404 Not Found" status and its associated error JSON.
The {{mock_server_url}} and {{userId}} variables are key. mock_server_url is a placeholder that Postman replaces with the actual URL of your running mock server. userId is a path variable that allows you to dynamically specify which user you’re requesting. Postman uses these to match incoming requests to the correct defined response.
The magic of mock servers lies in their ability to simulate different states of an API without any actual backend logic. You can define responses for success, various error codes (400, 401, 403, 404, 500), rate limiting (429), or even simulate slow responses by adjusting the responseTime. This allows you to build and test your client-side application thoroughly, ensuring it handles all expected (and unexpected) API behaviors gracefully.
You can even use Postman’s scripting capabilities within mock server responses. For example, you could write a pre-request script on the mock server itself to dynamically generate response content based on request headers or query parameters, making your mock even more sophisticated.
The most surprising thing about Postman Mock Servers is how easily they can decouple development. You can define an API contract using OpenAPI or Postman’s collection format, spin up a mock server based on that contract, and have frontend developers start building and testing their UIs against the mock while backend developers implement the actual API. This parallel development drastically speeds up the entire process.
The core mechanism for matching requests to responses is Postman’s request matching logic. It prioritizes exact URL matches, then method matches, and can also consider headers and body content if you configure it to do so. For more complex routing, you can define multiple requests in your collection, each with its own set of responses, and Postman will try to find the best match.
When you’re setting up a mock server, Postman generates a unique URL. This URL is typically http://<mock-server-id>.mock.pstmn.io for cloud-hosted mocks or http://localhost:<port> for locally run mocks. You can then configure your client application or other tools to point to this mock URL instead of your actual API endpoint.
The next thing you’ll likely want to explore is using dynamic variables within your mock responses. For instance, you could have a mock response that returns a different id each time it’s called, or generates a unique token, allowing you to test scenarios where those values change.