Mocking with examples

Mock servers simulate an API by returning predefined data, enabling you to develop or test against an API before it's production-ready (or without using production data). In Postman, mock servers rely on examples saved in a collection to return mock data. Follow the steps below to get a hands-on demonstration of how mock servers and examples work together, and to learn how you can integrate them into your API workflow.


Creating 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 see how your examples are used to return data.

Step 1 - Send a request

In Postman, open a new request by selecting + or by selecting New > HTTP Request. Leave GET as the method, and for the request URL enter When ready, select Send.

This request calls the Postman Echo service which you can use to test REST or SOAP clients and make sample API calls. The resulting response displays in the response pane below the request.

Send a request

Step 2 - Save the request to a collection

Select Save to save the request in a collection. Collections are groups of requests that you can use to organize your work and create API workflows.

Save a request

Select New Collection at the bottom of the Save Request dialog box. Enter C1 for the collection name and select Create. Then select Save to save the request to the new collection.

Save a request dialog box

Step 3 - Save a response as an example

To save the response you received from the Postman Echo service, select Save Response > Save as example. The example is saved underneath the request, inside the C1 collection.

Save an example

Select Collections in the left sidebar, expand the C1 collection and the request, and then select the example to open it.

Open an example

To rename the example, select the edit icon Edit icon next to the name. Rename the example E1. Note that the request method, URL, and status code are all saved as part of the example. Postman uses these items to determine which responses are returned by a mock server.

Rename an example

Step 4 - Create a mock server for the collection

Now that you've added an example to your collection, you're ready to set up a mock server. Select Collections in the left sidebar. Select the three dots Three dots icon next to the C1 collection, and then select Mock collection.

Mock a collection

For Mock server name, enter M1. You can also specify other details for your mock server as needed:

  • Collection is already set to C1, as you chose to mock this collection.
  • If your collection has multiple release tags, you can select the Tag to use. Since this is a new collection, you can only select Current.
  • If your saved example uses environment variables (like {{base_url}}/my/path), you must select the corresponding Environment or the mock server won't work. In this case, the example doesn't use any variables, so you can select No Environment.
  • By default, mock servers are publicly accessible. If you select the Make mock server private check box, the mock server will no longer be public. You can share it with team members and provide permission to edit or view. For now, do not select this check box.

When you're done configuring the mock server, select Create Mock Server. You can access the mock server at any time by selecting Mock Servers in the left sidebar.

Create a mock server

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

Step 5 - Send a request to the mock server

Now that you've created the mock server M1, you can try sending a request to the mock endpoint.

First, copy the mock server URL. Select Mock Servers in the left sidebar, select the M1 mock server, and then select Copy Mock URL.

Copy mock URL

Next, create a new request by selecting + or by selecting New > HTTP Request. Paste the mock URL into the new request and select Send.

Mock server error response

Sending this request returns an error. The reason is because you did not add a path to the mock server URL, and there is no matching saved example with an undefined path and the request method GET. Responses returned by the mock service are entirely dependent on the URL and method in your saved examples.

You do, however, have a saved example with the path /get and the request method GET. Add /get to the end of the mock server URL and send the request again. This time you receive the expected response from the mock server.

Mock server correct response

Step 6 - Add another example

To further demonstrate how responses from the mock service are entirely dependent on your saved examples, try adding another example to the C1 collection. Repeat steps 1 to 3 above to save a request to the collection and then save the response as an example E2, this time using the request URL

Add a second example

Sending a GET request to returns a 404 error, which you saved as another example. The collection C1 now has two requests and two saved examples:

  • Example E1: GET request to path /get
  • Example E2: GET request to path /test

Finally, repeat step 5 above, but this time add the path /test to the end of the mock server URL when sending the request. This returns the expected 404 response.

Send another request to the mock server

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 have 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 should match.

Generating random data with dynamic variables

As you've seen in this demonstration, you define the data to be returned by the mock server in your examples. However, there may be cases when you want the mock server to return a response containing random data.

To have your mock server return random data, use dynamic variables in your example's response body. Dynamic variables are resolved as part of the mock server response and replaced with random data. Dynamic variables are useful for generating random data when mocking an API, and you can use them for exploratory testing and writing rich, data-driven tests.

For instance, your example's response body might contain dynamic variables as follows:

    "name": "{{$randomFullName}}",
    "userName": "{{$randomUserName}}",
    "location": "{{$randomCity}}",
    "company": "{{$randomCompanyName}}",
    "jobTitle": "{{$randomJobTitle}}",
    "updatedAt": "{{$timestamp}}"

When you call the mock server endpoint, you'll see the response data change to something like:

    "name": "Cielo McClure",
    "userName": "Aurelie.Lockman",
    "location": "Kubhaven",
    "company": "Runolfsdottir, Bernhard and Hodkiewicz",
    "jobTitle": "Direct Branding Liaison",
    "updatedAt": "1565088856"

See Dynamic Variables for a full list of dynamic variables for generating random data.

Using query parameters

Postman's mock service uses a matching algorithm to select the most appropriate saved example to return in response to a request. As part of this algorithm, the mock server looks at the query parameters when matching requests to saved examples. If you have examples that differ only in their query parameters, you can mock different responses for different query parameters on the same request path. In this case, the mock server will return the exact response matching that request path and the corresponding query parameters.

Here's a scenario that illustrates how matching query parameters works:

  • The collection Query Params Demo has one request Request1 with two examples, Example1 and Example2.

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

    Query parameters example 1
  • In Example2, the parameter id has a value of 5:

    Query parameters example 2
  • In this scenario, Example1 and Example2 are passing 1 and 5 respectively. 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 passed parameters.

    Query parameters mock response

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

Mocking 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.

Query parameters example 1

Also make sure to pass the x-mock-match-request-body header with a value of true when sending a request to the mock server URL.

Query parameters example 1

Last modified: 2021/12/08