Mock your API using saved response examples

Mock servers simulate an API by returning predefined data, so you can develop or test an API before it's ready for production (or without using production data). In Postman, mock servers rely on examples saved in an HTTP collection to return mock data.

Follow the steps below for a demonstration of how mock servers and examples work together, and to learn how you can integrate them into your API workflow.

Create a mock server

The steps below walk you through the process of creating a mock server in Postman. First, you'll set up some basics that are required for mock servers to work. Once your mock server is up and running, you'll send requests to it and learn how your examples are used to return data.

Send a request

Create an HTTP GET request that calls the Postman Echo service. You can use this service to test REST or SOAP clients and make sample API calls.

To create and send a request, do the following:

1. Select New > HTTP, or select to open a new tab.
2. Select GET as the method, and enter https://postman-echo.com/get?test=123 as the request URL.
3. Select Send.

Save the request to a collection

Create a new collection and save the request to it. Collections are groups of requests that you can use to organize your work and create API workflows.

To save the request in a new collection, do the following:

1. Select Save to save the request.

   

2. (Optional) Give your request a new name.

3. Select New Collection to create a new collection.

4. Enter C1 for the collection name and select Create.

5. Select Save to save the request to the new collection.

   

Save a response as an example

Save the response you received from the Postman Echo service as an example.

1. Select Save Response. The example is saved underneath the request in the sidebar, inside the C1 collection.

   

2. To rename the example, select the example name and rename the example to E1. The request method, URL, and status code are all saved as part of the example. Postman uses these items to decide which responses the mock server returns.

   

Create a mock server for the collection

After you add an example to your collection, you can set up the mock server.

You can also create a mock server using the Postman API.

To create a mock server for the collection, do the following:

1. Select Collections in the sidebar.

2. Select View more actions next to the C1 collection, and then select Mock collection.

   

3. For Mock Server Name, enter M1. You can also specify optional details for your mock server, such as the environment if your example uses variables or whether you want to make the mock server private.

4. Select Create Mock Server. You can access the mock server by selecting Mock servers in the sidebar.

   If Mock servers isn't available in the sidebar, you can add it by selecting Configure workspace sidebar.

   

Send a request to the mock server

After you create the mock server, you can send a request to the mock endpoint.

1. Select Mock servers in the sidebar.

2. Select the M1 mock server, then select Copy Mock URL to copy the mock server URL.

   

3. Create a new request by selecting New > HTTP, or selecting to open a new tab.

4. Paste the mock URL as the request URL, then select Send.

   

   The request returns an error because the mock server URL doesn't have a path appended to the end. The path appended to the end of the mock server URL must match the path in the example's request URL (/get). The method selected in the mock server and example must also match. Responses returned by the mock service depend on the URL and method in your saved examples.

5. To send a request to the mock server, add /get to the end of the mock server URL and select Send.

   

Add another example

You can add another example to test how responses from the mock service depend on saved examples.

1. Create and send a request. Select GET as the method, and enter https://postman-echo.com/test as the request URL.

   The GET request to https://postman-echo.com/test returns a 404 Not Found status code.

2. Save the request to the C1 collection.

3. Save the response as an example. Rename the example to E2.

   

4. Send a request to the mock server. Update the path at the end of the mock server URL to /test and select Send. The mock server returns the expected 404 Not Found status code.

   

Your examples can vary depending on the URL endpoint, request method, or status code. If you have multiple examples, you can choose to save each example under a unique endpoint URL, like you saw in this demonstration with /get and /test. If you've saved examples with different response status codes, you can send an authenticated request to the mock server along with the x-mock-response-code header specifying which integer response code your returned response needs to match.

Use query parameters

Postman's mock service uses a matching algorithm to select the best saved example to return in response to a request. As part of this algorithm, the mock server looks at the request's path and query parameters, and then matches the request to a saved example. If you have examples with the same request path but different query parameters, you can mock different responses for different query parameters on the same request path.

The following scenario demonstrates how the matching algorithm selects the best saved example:

• A mocked collection has one request named Request1 with two examples named Example1 and Example2.

• In Example1, the parameter id has a value of 1.

  

• In Example2, the parameter id has a value of 5.

  

• In this scenario, Example1 and Example2 have the same request path (/get) but they each have a query parameter (id) with different values. When you send a request to the mock server URL and pass these different query parameters, Postman returns the exact response that matches both the path and the query parameters.

  

If no exact match is found, Postman returns the best response based on its matching algorithm.

Mock GraphQL queries

Postman's mock service enables you to mock GraphQL queries. To mock GraphQL queries, make a request to the mock server using the request path and request body saved in the examples in the mocked collection.

Make sure to set the Content-type header to application/json in your examples.