Setting up mock servers

Mock Servers allow you to simulate your API data. By saving example responses for your requests, you can create a mock server that will return your example response instead of connecting to your actual API, for example in cases where you do not have a backend yet, or are experimenting and don't want to connect to your real data source.

You can create mock servers from Postman, from the web dashboard, and using the Postman API. You will need a Postman account to set up a mock server.

Each mock server in Postman is linked to a collection. Postman matches requests and generates responses for mocks from the examples saved for the collection requests. You can create a mock server even if you don't have an existing collection.

Contents

Creating mock servers in-app

You can create a mock in several ways in the Postman app:

Mocking from the New button

The video below runs you through the steps in creating a mock server from the New button in the Postman app.

Mock creation flow using New button

To create your mock server, click the New button in the top left of the header toolbar.

Start by clicking the New button

Click Mock Server in the Create New tab.

Choose "Mock Server" from the dialog box

Choose whether you want to mock a new API or an existing collection. If you create a new API to mock, you will select a request method and enter the request path, response code, and response body. If you use an existing collection to mock, you will select a collection from a list of existing or team collections.

Set request path and response body

When you have selected or created the request you want to mock, click Next.

In the Set up the mock server tab, you can configure your mock server.

  1. Enter the name of the mock.
  2. Select an environment (optional).
  3. Check the checkbox if you want to make the mock server private.
  4. Check the checkbox if you want to save the mock server URL as an environment variable.
  5. Click Next to continue.

If your mock server is 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.

Set mock server configuration

The number of calls made to mock servers may be limited by your Postman account. Check your usage limits.

In the Next steps tab, you will see a list of suggested next steps to maximize the effectiveness of your mock server.

Next steps after mock is created

Mocking from the Launchpad

Launchpad appears by default when you launch the Postman app. To create a mock server, open the Postman app, navigate to Start something new > ... View More > Create a mock server.

Follow the process outlined in the New Button section to complete the mock server setup steps.

At the bottom, you can choose whether you want the Launchpad tab to display each time you open Postman by toggling the Open Launchpad option on or off.

Mocking from an API

You can create a mock server from an existing API. Navigate to the API you'd like to add a mock server to, then click Develop. Select Add Mock Server, then choose between creating a new mock server or adding an existing one.

This will launch the Create mock server modal. Follow the process outlined in the New button section to complete the mock server setup.

Create mock from API Dev

Mocking from the Collections sidebar

You can create a mock server from an existing collection in the left sidebar. To do that, expand the collection details pane, switch over to the Mocks tab in the pane, and click Create a mock server.

Create new mock server from collection sidebar

This will launch the Create mock server modal. Follow the process outlined in the New Button section to complete the mock server setup steps.

If you already have mock servers created from the same collection, you will see an Add mock button instead of Create a mock server.

Create new mock server from collection sidebar when there are existing mock servers

Mocking from history

You can create a mock server from the requests saved in the history of your Postman app.

Mocking a single request

You can mock a single request from the History tab in the left sidebar. Hover over an entry, and click View more actions (...) to expand the dropdown menu. Choose Mock Request.

Create new mock server from history request

This will open the Set up the mock server modal. Pass the values outlined in the New button section. Click Create Mock Server.

This process of creating a mock server will also create a collection with the same title as the mock server. This collection will have a copy of the same request that you chose from the History sidebar. The mock server created is tied to this new collection.

New collection created when creating mock server from history request

Mocking all requests made on a specific date

You can create a mock server from History for all the requests you made on a specific date, creating a new collection at the same time.

In the Postman app, click History.

History tab

Next to the date you want to mock all the requests for, click the ellipsis (...) > Mock Requests.

Ellipsis and mock requests

The Set up the mock server modal will open.

In the modal, give your mock server a name. You also have the option to connect an environment to the mock server, make the mock server private, and to save the mock server's URL as an environment variable. Click Create mock server.

Mocks modal

If you choose to make your mock server private, you'll have to generate an API key.

The "Next steps" modal will appear with an overview of your new mock server's details. Note the mock server's URL because you'll need it to make requests that return mock data.

Mocks modal

Creating the mock server will also create a collection with the same name as the server. The collection will have a copy of each request made on the date you chose in your History. All requests from this collection will be made to the server you just created.

Mocks modal

Mocking from Collections in Browse view

You can create a mock from an existing collection from the Browse view. Click the Browse toggle button on the bottom right of the Postman app. Change to the Collections tab for the current workspace. Click the View more actions (...) button for the corresponding collection. Select Mock Collection from the dropdown.

Create new mock server from browse view

This will open the Create mock server modal. Follow the steps to finish creating the mock server.

Creating mock servers in the web dashboard

You can create a mock server from the Web dashboard with existing collections and environments. Login to your Postman team dashboard, and navigate to your workspace by clicking your workspace name. In the workspace dashboard, click the Mock servers tab.

Mock servers web dashboard

Click the button to create a new mock server, and you will see the configuration screen. Set the relevant configuration.

Mock servers web dashboard configuration

  1. Enter the name of the mock.
  2. Select a collection to mock.
  3. Select a version tag of the collection to use for the mock. Leave it to CURRENT if you want to the mock server to use the latest version of your collection.
  4. Select an environment to use with the mock (optional).
  5. Select the checkbox if you want to make the mock server private.
  6. Click Create Mock Server to create the mock and go back to the Mock servers dashboard.

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

Using free mock server calls

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

You can check your usage limits in the Postman API or account usage page.

Editing and deleting mock servers

You can edit or delete existing mock servers in Postman. The following properties of a mock server can be updated through the Postman app and Postman Dashboard:

  • Name of the mock server
  • Version tag of the underlying collection
  • Environment associated with the mock server
  • Private or public status of the mock server

Postman Mock Server edit options

In the Postman app, you can edit or delete a mock server from the Collections pane or from the Mocks listed in Browse mode. You can also edit or delete a mock server from the Postman Dashboard.

Editing mocks from the Collections pane

  1. In the Collections pane, click the arrow (>) next to the name of the collection to expand the panel to the right. Postman Mock Server edit options
  2. At the top of the panel, click the Mocks tab. Postman Mock Server edit options
  3. Hover over the name of the mock server you want to edit and click Edit. Postman Mock Server edit options

Deleting mocks from the Collections pane

  1. In the Collections pane, click the arrow (>) next to the name of the collection to expand the panel to the right. Postman Mock Server edit options
  2. At the top of the panel, click the Mocks tab. Postman Mock Server edit options
  3. Hover over the name of the mock server you want to delete and click Delete. Postman Mock Server edit options

Editing mocks in Browse mode

  1. At the top, click the Mocks tab. Postman Mock Server edit options
  2. Next to the name of the mock server, click the ellipsis (...) > Edit. Postman Mock Server edit options

Deleting mocks in Browse mode

  1. At the top, click the Mocks tab. Postman Mock Server edit options
  2. Next to the name of the mocks server, click the ellipsis (...) > Delete. Postman Mock Server edit options
  3. Click Delete. Postman Mock Server edit options

Editing mocks from the Dashboard

To open the Dashboard, sign in to Postman from your browser.

  1. Open the workspace or collection with the mock server you want to edit.
  2. Click Mocks or Mock Servers at the top of the page.
  3. Hover over the name of the mock server and click Edit. Edit mocks

Deleting mocks from the Dashboard

  1. Open the workspace or collection with the mock server you want to edit.
  2. Click Mocks or Mock Servers at the top of the page.
  3. Hover over the name of mock server and click Delete. Delete mocks
  4. Click Delete Mock Server. Delete mocks

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 the Postman app by clicking it in Collections, in APIs, or by switching to Browse > Mocks and clicking the mock name. Your mock call log will open in the web dashboard—you can also open it from the collection in the browser, by selecting Mock Servers.

Mock List Browse View

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

Mock Call Log List

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. You can drill down into response data returned by a mock call.

Mock Call Log

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.

Mock Call Error

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: