Using Postman's mock servers requires a collection with requests and saved request examples. You can save as many examples to a collection as you want, and the mock server will return these examples predictably. Postman uses a matching algorithm to decide which examples to return.
When you create a mock server, Postman associates a particular collection (and optionally an environment) with the new mock server. In the scenario below, the collection C1 is associated with the new mock server named Test Mock with the ID M1.
When you call the mock server M1 using the mock server URL https://M1.mock.pstmn.io
, the mock service retrieves all saved examples for the associated collection before it begins the matching process.
After the mock service has all the saved examples for the collection, it iteratively pairs the incoming request with the closest matching example.
The incoming request can have several configurable variables, such as requestMethod
, requestPath
, requestHeaders
, requestBody
, and requestParams
. The requestMethod
variable corresponds to any valid HTTP request method (such as GET
, POST
,PUT
, PATCH
, or DELETE
), and the requestPath
refers to any valid string path (such as /
, /test
, /test/path
, or /test/path/1
).
You can use other optional headers like x-mock-response-name
or x-mock-response-id
to further specify the example to be returned based on the name or the UID of the saved example. You can get the example UID by using the Postman API to get a collection and searching for your example in the response. The UID has the syntax <user_id>-<response_id>
.
To match an incoming request with the closest matching example, Postman uses the following algorithm.
The mock service fetches all examples in the mocked collection and converts them into Postman response objects using the Postman Collection SDK. If the conversion process fails for an example, resulting in a response that isn't in the expected format, the example is removed from the matching process.
The mock service also fetches the environment associated with the mock server (if there is one). Collection variables and environment variables in the examples are then populated with data.
Any responses that aren't the same HTTP method type as the incoming request are removed from the matching process. For example, if the mock request was POST
to https://M1.mock.pstmn.io/test
, all saved examples for which the method type isn't POST
are disregarded.
The matching algorithm checks any custom headers passed in the incoming request in the following order:
If the x-mock-response-code
header is provided, the algorithm filters out all examples that don't have a matching response status code.
If the x-mock-response-id
header is provided, the algorithm selects the example with the matching response ID and returns the example as the response. If no example is found with a matching ID, the matching process stops and Postman returns an error.
If the x-mock-response-name
header is provided, the algorithm selects the example with the matching name and returns the example as the response.
200
response status code.200
response status code, Postman returns the first example in the sorted list.The matching algorithm compares the /path
of the incoming request with the /path
of each saved example. The algorithm then assigns a score to each example based on how close the match is between the paths.
An example starts with a score of 100. The algorithm goes through the following steps in order and stops when a match is made. The score is then adjusted based on the step that resulted in a match. If a match can't be made, the example is removed from the matching process.
URL matching step | Matching score change |
---|---|
URL match is perfect | No change |
URLs match after removing trailing slashes (/ ) | Reduced by 5 |
URL match is case insensitive | Reduced by 10 |
URLs match after removing trailing slashes (/ ) and the match is case insensitive | Reduced by 15 |
URLs match after removing wildcard variables | Reduced by 20 |
URLs match after removing alphanumeric IDs | Reduced by 21 |
URLs match after removing trailing slashes (/ ) and alphanumeric IDs | Reduced by 25 |
URLs match based on a document distance algorithm | Reduced by 30 |
For example, if the request's URL is
https://M1.mock.pstmn.io/test
and the example's URL ishttps://postman.com/about
, the algorithm compares/test
with/about
. In this case the paths don't match, so the corresponding example is skipped, and the algorithm moves to the next example.
After matching URLs, the algorithm examines the parameters for each example (such as {{url}}/path?status=pass
). The matching score is further adjusted based on the number of parameter matches, partial parameter matches, and missing parameters.
The number of matching parameters is used to calculate the matching percentage. The matching percentage equals the number of parameter matches divided by the sum of all parameter matches, partial parameter matches, and missing parameters.
Parameter matching result | Matching score change |
---|---|
All parameters match (case sensitive) | Increased by 10 |
Some parameters match | Increased by 10 multiplied by the matching percentage |
No parameters match | Reduced by the number of missing parameters (maximum reduction of 10) |
You can enable header and body matching in the mock server configuration. You can also enable header and body matching by passing the custom header x-mock-match-request-body
or x-mock-match-request-headers
with the request. (These custom headers have higher precedence than header or body matching values specified in the mock server configuration.)
When header and body matching are enabled:
When body matching isn't explicitly enabled, the matching algorithm still considers the request body. If an example's body matches the request body, the example's matching score is increased by 5. If the example's body doesn't match the request body, the example's score isn't adjusted, and the example isn't removed from the matching process.
The matching algorithm checks the matching scores of the remaining examples and returns the example with the highest score.
200
response status code.200
response status code, Postman returns the first example in the sorted list.All variables in an example's request that don't exist in the mock server's associated collection or environment are treated as wildcard variables. Wildcard variables act as capture groups for dynamic URL segments. This is useful if some segments of the API's URL map to resource identifiers, like user IDs, user names, or file names.
For example, you can mock an endpoint that returns a user profile by ID. The endpoint takes in the user ID from the URL and returns the user ID in the response. On calling GET {{url}}/users/{{userId}}
, the endpoint returns:
{
"id": 2,
"name": "Carol"
}
To match a request like this in your mock server, you can use a variable in the request URL of your example. You don't need to hard-code values in the example. Instead, you can match any request sent to your mock server that matches the pattern GET /users/<userId>
. To do this, replace the dynamic segments.
Wildcard matching applies to entire URL path segments. The same example, GET {{url}}/users/{{userId}}
, can serve GET /users/1
, GET /users/100
, or even GET /users/carol
. But this example won't match GET /users/another/segment
.
You can place the same variables in the example's response to use their captured values. In this case, you can add a request body for the same example as follows:
{
"id": {{userId}},
"name": "Carol"
}
This will pass the value captured from the wildcard segment to the same variable name into the response.
Wildcards in response bodies aren't part of the matching algorithm.
If the mock server isn't returning the example you expect for a request, try the following:
x-mock-response-name
or x-mock-response-id
header in your request. Postman will return the example with the matching name or UID.x-mock-response-name
header. Alternatively, you can use the x-mock-response-id
header to get the correct response. To find the ID of a saved example, select it in the sidebar, then select Info in the right sidebar.x-mock-response-code
header in your request to specify the response status code you want. Any examples that don't have the matching response status code are removed from the matching process.Last modified: 2024/10/18