Setting up mock servers

You can make requests that return mock data defined within Postman if you do not have a production API ready, or you do not want to run your requests against real data yet. By adding a mock server to your collection and adding examples to your requests, you can simulate the behavior of a real API.

When you send a request to a mock server, Postman will match the request configuration to the examples you have saved for the request and respond with the data you added to the example. You will see any existing mocks in your workspace from Mock Servers on the left of Postman.

You need to be signed into a Postman account to create a mock server.

Mocks quick start

To try out a mock server, carry out the following steps:

• Make a request to any API in Postman–making sure your request is saved to a collection.
• Select at the top right to view more actions, then select Add example. Postman will automatically populate the example with the response you received when you sent the request.
• In Collections on the left, select the collection and open the Info using the button on the right. Click Create mock server.
• Give your mock a name, leaving the default tag selected, and the delay option unchecked. Click Create Mock Server.
• Copy the mock URL and go back into your request. Replace the base part of the URL with the mock server URL (everything before the path e.g. up to /customers).
• Click Send—Postman should return the example response you saved for the request, this time from the mock server.
• Open the example again and alter the mock response JSON, then save it and send the request again—you will see your edited mock response.

Contents

• Creating mock servers
  • Configuring mock details
• Making requests to mocks
  • Using HTTP access control for a mock
• Viewing mock calls
  • Troubleshooting mock calls

Creating mock servers

You can create mock servers from an existing collection, or Postman will create a new collection for your mock server. You can create a new mock from scratch, from a collection, from the New button, from an API, or from your history.

Creating a mock from scratch

In Mock Servers on the left of Postman, click the + button.

Select an existing collection or add a new one (adding an initial request for a new one).

Configure your mock details.

Creating a mock from a collection

Open a collection in Postman, and open the Info from the button in the right sidebar. Click Create mock server.

Configure your mock details.

Creating a mock from the New button

Click New and choose Mock Server.

Choose whether you want to mock an existing collection or generate a new one for your mock (adding a request).

Configure your mock details.

Creating a mock from an API

If you want to generate a mocks collection from an API or add a mock to an API collection:

1. Open an API version from APIs on the left of Postman.

2. On the API version Overview tab, next to Mock Servers, select + and choose Create new mock server or Add existing mock server.

   • Create new mock server: Select a method for how to base your mock server:

     • Generate from API schema: To create a mock server based on a collection generated from your schema, enter a collection name, and configure how the collection will be generated by clicking Show advanced settings. Select Generate Collection and Continue, and then configure mock details.
     • Use an existing collection: Select a collection from the dropdown list. Select Select Collection and Continue, and then configure mock details.
     • Create a new collection: Enter the requests your collection will contain. Select Create Collection and Continue, and then configure mock details.

   • Add existing mock server: Select an existing mock server in the list, and then select Add Mock Server.

Creating a mock from history

You can build a mock based on requests from your Postman history. In History on the left, hover over a request or date and select > Mock Request.

Configure your mock details.

Configuring mock details

When you create a mock server you will give it a name, choose a release tag (if your collection has a specific release you want to mock), choose an optional environment to run the mock against, and configure a delay before the server sends your mock responses (choosing to simulate 2G/3G networks or specify a custom delay in milliseconds).

If you choose to make your mock server private, you will need to add a Postman API key in the request header: x-api-key:<Your-Postman-API-key>. You can share the collection and your collaborators can use their Postman API keys to consume the mock.

Not all configuration options may be available, depending on the method you used to create the mock server. For example, you don't need to select a release tag if you created a new collection because a new collection won't have any tags.

With your details in place, click Create Mock Server.

You can also opt to save the mock URL to an environment variable which you can then reference in your requests by making the environment active before sending.

Postman will display the details you'll need to use the mock (you can also get these from the collection at any time).

Click Copy Mock URL to begin making requests to your mock.

You will see details of the mock in the collection overview info on the right.

To edit or delete a mock, select Mock Servers on the left, then select next to the mock's name.

Making requests to mocks

With your mock URL, you can start making requests right away. Make sure the request you want to mock has at least one example added to it.

Open a tab (or edit the address in an existing tab) and add the mock URL:

https://<mock-id>.mock.pstmn.io/<request-path>

For example:

https://3589dfde-f398-45cd-88eb-b0fa0192fc3f.mock.pstmn.io/matches

The mock URL includes the ID for the mock and the path for the request with a saved example.

If you save your mock URL to a variable, you can reference it across requests—for example if you have a production server and a mock server, you could have an environment for each one with the same variable name in each for the mock URL. With your requests using the variable, you can then switch between the two environments.

You can also retrieve your mock ID from the Postman API

When you Send a request to your mock server URL it will send back one of the examples you added to the request with the same path and method. (You can provide multiple examples and Postman will return the one that matches your request configuration most closely).

If you configured a delay for your mock server, Postman will wait the specified period of time before sending the response.

Your Postman account gives you a limited number of free mock server calls per month. Check your usage limits.

Using HTTP access control for a mock

In addition to using the Postman app to make requests to mock endpoints, you can also make those requests in a browser.

A web browser makes a cross-origin HTTP request when it requests a resource from a domain, protocol, or port that's different from its own. Cross-Origin Resource Sharing (CORS) is a standard that defines a way in which a browser and server can interact securely, in this case referring to how a web browser interacts with the mock endpoints hosted on the Postman server.

CORS is enabled for Postman mock servers. As a result, you can stub your web apps with mocked data using the mock endpoints. Development or production web apps can then make requests to your Postman mock endpoint and receive example responses.

Viewing mock calls

You can view and search the details of calls to your mock servers using the mock call log. Open a mock from Mock Servers on the left of Postman. Your mock overview and call log will open.

The mock call log lists an overview of calls made to the mock url, together with request and response details you can drill down into.

Mock call log entries indicate the time a request was sent, the request method and path, and a response overview. Click an entry to see more detail on request headers and body, or response headers and body.

Use the search field to find particular calls, and the refresh button at the top of the list to view up to date requests.

Troubleshooting mock calls

You can use the mock call log to troubleshoot your requests to mock servers.

If you see No matching requests listed in the Response column, this may mean that your mock server is not setup correctly. Make sure you have an example saved for the request in the collection you have the mock connected to.

In the case of a service outage, you will get a 502/503/504 response. Please subscribe and check the Postman status page for updates if you encounter this.

Next steps

For more information about mock servers, see the following resources:

• Mocking with examples
• Mocking with the Postman API
• Matching algorithm