Examples

This topic covers:

• What is an example?
• Why use examples?
• Adding an example
• Accessing your saved examples
• What happened to the ‘Save Response’ feature?
• How your examples appear in Postman documentation

What is an example?

An example is a tightly coupled request and response pair.

For instance, as shown in the image below, ‘200 OK custom response’ is the name of an example. To complete the example, you can mock an ‘example request’ and an ‘example response’.

Developers can mock a request and response in Postman before sending the actual request or setting up a single endpoint to return the response.

To establish an example during the earliest phase of API development:

• Requires clear communication between team members.
• Aligns their expectations.
• Helps developers and testers start more quickly.

Why use examples?

Often it’s useful to mock and save a couple of example responses with a request, such as a status code, to make your API more understandable.

Let’s say you want to build an API with an endpoint that does not yet exist, or your server isn’t ready. You can mock raw responses and save them. Then, you’ll be able to generate a mock endpoint for each of them using Postman’s mock service.

Developers can make requests to the mock endpoint and start front-end development or write tests based on the mock response returned from the mock endpoint.

Adding an example

Suppose you are working on a request that is saved in a collection. You can add examples to this request with a new custom response or the response from the server.

New custom response

You can create examples that define how the response should look. The image below outlines the steps for creating an example with a new response. Note that the base request is loaded as an ‘example request’ in the Example editor.

Response from the server

After you receive a response from a server, you might want to save the current request and response pair as an example. The steps to save the current request and response pair are similar to creating a new response from scratch. Note that the base request and the response from the server are loaded as the ‘example request’ and ‘example response’.

Later you can return to your base request and resume by clicking on the request name in the upper left corner of the builder.

Accessing your saved examples

Click on the Examples dropdown in the upper right corner of the builder to access all your saved examples.

What happened to the ‘Save Response’ feature?

Saving responses has been a Postman feature for a long time. Over time our users wanted to edit responses before saving them, and add new responses. We created Examples to provide that functionality.

You can save responses as before, but now you can edit them whenever you want. To access previously saved responses, click the Examples dropdown.

How your examples appear in Postman documentation

You can publish Postman API documentation to the web with a single click. Examples display in your API documentation and provide additional details and clarification for your API.

You can edit these examples with real-time updates to the documentation!

This behavior allows teams to mock an example request and response, in addition to simulating the endpoint using mock servers. Front-end and back-end developers and testers can all begin working in parallel, based on the agreed-upon example.