Mock your API using saved response examples

Mock servers simulate an API by returning predefined data, enabling you to 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 a 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.

Contents

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 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.
Send a request

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 icon Save to save the request.

    Save a 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 request to a new collection

Save a response as an example

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

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

    Save an example
  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.

    Rename an example

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 the more actions icon More actions icon next to the C1 collection, and then select Mock collection.

    Mock a 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 and 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.

    Create a mock server

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 the copy icon Copy icon to copy the mock server URL.

    Copy mock 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.

    Mock server error response

    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 successfully send a request to the mock server, add /get to the end of the mock server URL and select Send.

    Mock server correct response

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.

  2. Save the request to the C1 collection.

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

    Add a second example

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

  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.

    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 needs to match.

Using 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 path and its query parameters, matching requests to saved examples. 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:

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

    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: 2023/10/23