Specifying examples

Examples show your API endpoints in action and provide additional details on exactly how requests and responses work. You can quickly add an example to a request just by saving a response, or create an example with a custom response to illustrate a specific use case. Once you've created examples, you can use them to set up a mock server or add more detail to your API documentation.

Contents

What are examples?

In Postman, an example is a tightly-coupled request and response pair. Each example is made up of a request part (method, URL, parameters, headers, and body) as well as a response part (status code, body, and headers). You create examples by adding them to requests in collections, and one request can have multiple examples.

Having multiple examples for one request is useful for illustrating the different ways an endpoint can respond to a request. You might have examples that respond with different status codes (such as 200 or 404) or that return different data (or no data at all).

Examples are useful in several ways. Developers and testers can refer to examples to better understand how an endpoint should function in different scenarios. Examples can also be used to set up mock servers, so developers and testers can start writing code against your API—even before it's complete. In addition, you can include examples in your API's public documentation to help anyone in the world who uses your API.

Adding an example

An example is always associated with a request in a collection, and a request can have more than one example. To quickly add an example to a request, send the request and then save the response as an example. You can also manually add an example to a request and define a custom response. After adding an example using either method, you can edit it at any time to make changes.

To ensure optimal performance of the Postman app, example responses should be no larger than 5 MB in size.

Saving a response as an example

When saving a response in Postman, you have the option to save it as an example.

  1. Select Collections in the sidebar.
  2. Open a request and select Send.
  3. In the response pane, select Save Response and then select Save as example.
Save a response as an example

Adding a custom example

With a custom example, you can define exactly how both the request and the response should look, including the status code and response body.

  1. Select Collections in the sidebar.
  2. Select the three dots Three dots icon next to a request and then select Add example.
  3. Enter a name for the example.
  4. Edit the request part of the example.
    • Add any parameters or headers as needed.
    • Enter the request body and select a content type.
  5. Edit the response part of the example.
    • Enter a Status Code (such as 200 or 404).
    • Enter the response body and select a content type.
    • Add any headers as needed.
  6. Select Save to save the example.
Add a custom example

Editing an example

Examples are stored in a collection below their associated requests. You can edit an example any time after adding it to remove sensitive tokens, change the status code, or make any other adjustments.

  1. Select Collections in the sidebar.
  2. Select a request, and then select an example to open it.
  3. Make any changes to the example request or response.
  4. Select Save to save the example.
Edit an example

Duplicating an example

Duplicate an example to quickly add a new example using an existing example as a base. You can then edit the copied example to change the name, status code, or any other part of the request or response.

  1. Select Collections in the sidebar.
  2. Select the three dots Three dots icon next to an example, and then select Duplicate.
  3. Make any changes to the example request or response.
  4. Select Save to save the example.

Deleting an example

Deleting an example removes it from the collection as well as from the associated API documentation. Any mock servers you have set up can no longer use the example to return a response.

  1. Select Collections in the sidebar.
  2. Select the three dots Three dots icon next to an example, and then select Delete.
  3. Select Delete to confirm.

Using examples in documentation

Postman automatically generates documentation for every collection you create. The generated documentation includes any examples that have been added to the collection. If you edit an example, the documentation is automatically updated with your changes.

Examples in documentation

Examples provide additional details and clarification for your API and help your team to collaborate on API development. Front-end developers, back-end developers, and testers can all work in parallel, using the examples in the documentation for guidance or to set up mock servers.

You can publish your documentation to make your examples publicly available to anyone in the world.

Next steps

Use examples to set up a mock server or include examples in your API documentation.

Last modified: 2021/11/04