Examples

Developers can mock a request and response in Postman before sending the actual request or setting up a single endpoint to return the response. Establishing an example during the earliest phase of API development requires clear communication between team members, aligns their expectations, and means developers and testers can get started more quickly.

What is an example?

An example is a tightly coupled request and response pair. For instance, in this illustration, ‘200 OK custom response’ is the name of an example, which contains an ‘example request’ and an ‘example response’.

Why use examples?

More often than not, it is useful to create and save a couple of example responses alongside a request – status codes for a 200, a 404, a 500, etc. – to make your API more understandable to others. Thus, a teammate looking at your API can quickly view these examples and get a good idea of the responses a particular request is going to return – all this, without having to hit ‘Send’ on the request.

Furthermore, let’s say that you are going to build an API with an endpoint which does not yet exist, or your server just isn’t ready. With examples, 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. With this setup, developers can makes requests to the mock endpoint, and get started on front-end development or writing tests based on the mock response returned from the mock endpoint.

Adding an example

Adding examples to each of your API endpoints involves just a few clicks. Let’s say you are working on a request that is saved inside a collection. You can add examples to this request with a new custom response or the response received from the server.

A new custom response

Examples let you define what the response should look like by letting you create your own custom responses from scratch. The illustration below outlines the steps for creating an example with a new response.

1. Click on the Examples dropdown.
2. Click the Add Example button. The base request gets loaded as ‘example request’ in the examples editor.
3. Enter the name of your example.
4. Edit the request part of the example.
5. Enter a status code.
6. Create a new response for your example.
7. Click the Save Example button in the upper right corner of the builder (CMD/CTRL + S) to save your example.

The response received from the server

After you’ve received a response from a server, you might want to save the current request and response pair as an example. Steps for doing so are similar to creating a new response from scratch.

Later on, you can go back to your base request, and continue right where you left off 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?

The ability to save responses has been available in Postman for a long time. However, our users wanted to edit these responses before saving them, and also to add new responses. Examples make all of this possible!

Responses can be saved to examples. Save responses, like before, but now you can edit them whenever you want. Access your already saved responses by clicking on the Examples dropdown.

How your examples appear in Postman documentation

You might already know that Postman has API documentation, published to the web with a single click. Examples are displayed in your API documentation, providing additional details and clarification for your API.

And you can always go back and edit these examples, with real-time updates to the documentation!

This allows teams to mock an example request and response, along with 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.