Mocking by API

You can mock a collection directly from Postman. Additionally, you can create a mock using the Postman API. Let’s walk through this step by step.

Set up a collection for mocking

In this example, we have a Collection testAPI with corresponding environment testAPIEnv. Let's set up a mock service to enable your front-end team to simulate each endpoint in testAPI and view the various responses.

Navigate to every request in the Collection testAPI that you would like to include in this simulation, and save responses with details about the response body, header or status codes that you would like to see returned by that endpoint. This example saves two responses with status codes of 200 and 401 for this particular request. Once you save the desired responses, the Collection is ready for mocking.

Note: In addition to mocking a collection with a saved response, you can also mock a request and response using examples.

saved responses

Retrieve information needed for mock creation

Let's retrieve the collectionId of testAPI using the Postman API. Get a list of all your Collections using the GET All Collections endpoint. Search for the name of your Collection and retrieve the uid from the results, which will be used as the collectionId in the next step.

get collection id

You can also use Postman to retrieve the collectionId. Find the Collection and hit View Docs. The collectionId is visible in the documentation url:{{collectionId}}

As an optional step, you can include an environment as a part of your simulation by retrieving the environmentId of testAPIEnv using the Postman API. Get a list of all your environments using the GET All Environments endpoint. Search for the name of your environment and retrieve the uid from the results, which will be used as the environmentId in the next step.

get environment id

Create a mock using the Postman API

Create a mock using the POST Create Mock endpoint with the collectionId and environmentId you retrieved previously.

Mocks are accessible to the public by default. If you want the mock to only be available privately, include "private": true.

create mock

Verify that the mock has been created using the GET All Mocks endpoint, and your Collection is now ready to be simulated.

Run the mock service

Mock your Collection using the following url:

  • mockId is the id that you received upon creating the mock and can be retrieved using the GET All Mocks endpoint.
  • mockPath is the path of your request that you’d like to mock, for example api/response.

Add the request headers:

  • Mock requests also accept another optional header, x-mock-response-code, which specifies the integer response code your returned response will match. For example, 500 will return only an HTTP 500 response. If this header is not provided, the closest match of any response code will be returned.
  • Similarly, other optional headers like x-mock-response-name or x-mock-response-id enable you to further specify the exact response you want by the name or 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 <user-id>-<response-id>. Without these optional headers, the mock will follow a matching algorithm to decide which example to return.
  • Mock requests also accepts optional headers x-mock-match-request-body for request body matching and x-mock-match-request-headers for matching incoming mock request headers. You must set x-mock-match-request-body header to true to enable request body matching. To enable incoming mock request header matching, you must ensure that x-mock-match-request-headers header is present in the request and its value is a comma-separated string of header keys that you want to match against in the saved examples. Header matching is case-insensitive.

request headers

Mock requests and responses with examples

In the previous example, a saved response was used to mock a collection. You can also mock a request and response using examples in Postman before sending the actual request or setting up a single endpoint to return the response. With examples, you can mock raw responses and save them. Then, you’ll be able to generate a mock endpoint for each of them using Postman’s mock service.

Last modified: 2021/09/23