Using the Postman mock service requires the following: a collection with requests, a mock server, and saved request examples. You can save as many examples to a collection as you please, and the mock server will return these examples predictably. But how exactly does the mock decide which example to return?
To begin, let’s start with an example.
When a mock is created using either the Postman API or the Postman app, a call is made to the Postman servers that associates a particular collection (and environment if you choose one) with a newly created mock. The collection
C1 that we just mocked is now associated with the new mock
When we use the mock
M1 via the mock URL
https://M1.mock.pstmn.io in the Postman app, the mock service will retrieve all saved examples from the Postman servers for that particular collection before it begins the matching process.
Now that the mock service has all the saved examples for the current collection, it will now iteratively pair the incoming request with the closest matching example.
The incoming request can have several configurable variables, such as
requestMethod variable corresponds to any valid HTTP request method (e.g.
DELETE, etc.), and the
mockPath refers to any valid string path (e.g.
If the mock was specified to be available only privately, the request will require an authentication header
x-api-key corresponding to the Postman API Key, and optionally accepts a header
x-mock-response-code corresponding to the desired response code of the mock request. For example, you could request a
500 response for a particular endpoint.
Other optional headers like
x-mock-response-id allow you to further specify the example to be returned by the name or by the uid of the saved example respectively. You can get the example response uid by using the Postman API to GET a Single Collection and searching for your example in the response. The uid has the syntax
Keeping these various configurable elements in mind, let’s take a look at the matching algorithm logic.
Properly formatted responses
Any responses that are not in the expected format are removed from the matching process.
Any responses that are not the same HTTP method type are removed from the matching process. For example: if the mock request you sent was
https://M1.mock.pstmn.io/test, all saved examples whose method type is not
POST will be disregarded.
Filter by URL
The matching process will now examine each saved example, and iterate over every possibility. Compare the
mockPath of the input URL with that of the saved example. If the input URL was
https://M1.mock.pstmn.io/test and the example currently being examined had a URL of
https://google.com/help, the mock service would compare
/help. While comparing URLs, a step-by-step matching is conducted. Each consecutive step that the matching algorithm traverses reduces the matching threshold of the current example response.
n + m.
n + 2m.
x-mock-response-code header is explicitly provided, filter out all examples that do not have a matching response code.
Highest threshold value
Sort the remaining filtered responses in descending order and return the response with the highest threshold value.
And there we have it! This is how the mock service finds and returns the appropriate response to a mock request.