Create and use a mock server using the Postman API

Set up a mock server to simulate the behavior of a real API for development or testing purposes. In Postman, you mock a collection by adding examples and creating a mock server. You can automate the process of setting up a mock server using the Postman API.

Follow the steps below to get a hands-on demonstration of how to mock a collection with the Postman API.

Set up a collection for mocking

In Postman, create a new collection called testAPI. Optionally, you can also create a new environment called testAPIenv. For this demonstration, you'll set up a mock server you can use to call each endpoint in the testAPI collection and view their responses.

Add a new HTTP request to the testAPI collection. In the example below, the collection has one request called Request 1 that sends a GET request to https://postman-echo.com/get?test=123. Feel free to add more requests if you like.

To send the request, open the first request in the collection and select Send. Then, in the response pane, select Save Response. Repeat this process for each request in the collection. Your mock server uses these saved examples to return mock data.

You can edit an example to include the specific response body, header, or status code that you want the mocked endpoint to return. A request can have more than one example, in which case the mock server will follow a matching algorithm to decide which example to return.

Retrieve the collection ID

To mock a collection using the Postman API, you first need to know the collection ID. You can retrieve the ID of the testAPI collection using the GET /collections endpoint of the Postman API. If you created an environment, you also need to retrieve its ID using the GET /environments endpoint.

Get the collection ID

Create a new request in Postman, leave GET selected for the method, and enter the following URL: https://api.getpostman.com/collections.

If you send the request, you'll receive an authentication error. To authenticate with the Postman API, add an x-api-key header to your request and sets its value to your Postman API key. (You can generate a new Postman API key if you don't already have one.)

Select Send to send the GET All Collections request. The response pane displays a list of all your collections. Search for the testAPI collection and locate the uid value. You will use this collection ID in the next step.

You can also find the collection ID in Postman. First, select Collections in the sidebar and select the testAPI collection. Then select Info in the right sidebar to access the collection ID.

Get the environment ID

Create a new request in Postman, leave GET selected for the method, and enter the following URL: https://api.getpostman.com/environments.

Make sure to add an x-api-key header with your Postman API Key, and then select Send. The response pane displays a list of all your environments. Search for the testAPIenv environment and locate the uid value.

You can also find the environment ID in Postman. First, select Environments in the sidebar and select the testAPIenv environment. Then select Info in the right sidebar to access the environment ID.

Create a mock server with the Postman API

After getting the collection ID (and optionally the environment ID), you can use the POST /mocks endpoint to create a mock server.

First, create a new request in Postman, select POST for the method, and enter the following URL: https://api.getpostman.com/mocks.

Next, add the following raw JSON code to the Body tab of the request, substituting your collection ID and environment ID:

{
  "mock": {
    "name": "testAPImock",
    "collection": "<your-collection-id>",
    "environment": "<your-environment-id>"
  }
}

By default, mock servers are public and can receive requests from anyone and anywhere (such as a browser, application code, or a curl command). If you don't want the mock server to be public, add the line "private": true to the request body.

As always, make sure to add an x-api-key header with your Postman API Key. When ready, select Send to send the request to the Postman API and create the mock server.

Get the mock server URL

To send a request to your mock server, you need to know the mock server URL. You can retrieve the mock server URL using the GET /mocks endpoint. Create a new request in Postman, leave GET selected for the method, and enter the following URL: https://api.getpostman.com/mocks.

Add an x-api-key header with your Postman API Key, and then select Send. The response pane displays a list of all your mock servers. Search for the testAPImock mock server and locate the mockUrl value. You'll use this URL to send a request to the mock server.

You can also find the mock server URL in Postman. Select Mock Servers in the sidebar, select the testAPI mock server, and then select Copy URL.

Send a request to the mock server

You're ready to simulate requests using your collection. To send a request to the mock server, use the mock server URL and append the request path: {{mockURL}}/path.

Try this yourself by simulating Request 1 in the testAPI collection. Create a new request in Postman, leaving GET selected for the method. For the request URL, enter your mock server URL and append the path from the request:

https://<your-mock-server-url>/get?test=123

There's no need to add an x-api-key header, as the mock server is public, so select Send to send the request. The response pane shows the response from the mock server.

Notice that the response is the same as the example you saved for Request 1. That's because the mock server uses the example to create a response. If you added more requests and examples to the collection, send them to the mock server using the mock server URL and the request path.

Add optional request headers

Postman mock servers accept optional headers you can use to customize how the mock server responds to requests. Using these headers, you can specify which saved examples the mock server will return. Without these headers, the mock server will follow a matching algorithm to decide which example to return in a response.

To add a custom header to a request, open the request and select the Headers tab. Enter the custom header in the Key field and then enter a Value for the header. You can type x-mock in the Key field to see a list of the available mock server headers.

Match a specific response code

Use the header x-mock-response-code to specify the HTTP response code the returned response will match. For example, 500 will return an example with the HTTP 500 response.

Match a response name or ID

Use the headers x-mock-response-name or x-mock-response-id to specify the exact response you want the mock server to return by matching the id or the name of the saved example. You can get the example response id or name by using the Postman API's GET /collections/{collectionId} endpoint and searching for your example in the response.

Make sure to use unique names for all saved examples in the mocked collection. If more than one example in the collection has the same name, you may not get the expected response when using the x-mock-response-name header. Alternatively, you can use the x-mock-response-id header to get the correct response.

Match a request body or header

Use the headers x-mock-match-request-body or x-mock-match-request-headers to specify the exact response you want the mock server to return by matching the headers or body of the saved example.

• To enable request body matching, set the value of x-mock-match-request-body to true.

• To enable request header matching, include the header x-mock-match-request-headers and set its value to a comma-separated string of header keys that you want to match in the saved examples. Header matching isn't case-sensitive.

You can also enable body and header matching in the mock server configuration.

Set a custom response delay

Use the header x-mock-response-delay to add a delay to the response from the mock server. You can specify a value from 1 to 180000 milliseconds. After receiving the request, the mock server waits the specified period of time before sending the response.

You can also specify a delay in the mock server configuration. The delay value set by the x-mock-response-delay header takes precedence over the value set in the mock server configuration.