Mock responses in Postman by using Examples

Postman recently introduced mock servers allowing developers to simulate an endpoint without spinning up a back-end server. Today, Postman is announcing Examples to take it one step further, or to be precise, one step earlier in the API development lifecycle.

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 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.

Click on the request name to go back to your base request
Accessing your saved examples

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

Access your saved examples by clicking on the examples dropdown in the upper right corner of the builder
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!

party popper 

Responses can now 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. 

Responses are now saved in examples, which you can access by clicking 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. 

smiling face with open mouth 

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

This is how your examples appear in Postman 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.

As always, the Postman team loves hearing feedback from the community, and based on your input, we work hard to build features that support you throughout the entire API development lifecycle. Examples are a simple, but powerful, way to get started more quickly and efficiently.

Examples are out on our Canary build, and will hit our stable builds this week. Latest Canary builds are available for download on OSX (x64) / Windows (x86 or x64) / Linux (x86 or x64) / ChromeCheck it out, and let us know what you think!

Update: Examples are currently available in our stable builds.

  • I've been waiting for this powerful feature. Thanks a lot Postman team.

  • Dmitry

    Hi!
    Thanks for making postman even more awesome!

    I have one question though. Is it possible to add some kind of dynamic content to the saved response? Say, in simplest case, if I call
    GET /products/12334
    then mock server would return 12334 as an "id" inside mock response?

    Is it possible or planned?

    • bhawna

      Hello Dmitry,
      That's a good suggestion! This is not supported currently, but we'll be making our mock service more powerful with time and this would be a great addition. Have added it as a feature request 🙂

  • Carlton

    How exactly do I access the "examples" section, I can't see any example option above my 'save' button as per you gif and have tried new chrome plugin and new canary version on Windows.

    Postman for Windows
    Version 4.11.0-canary02
    win32 6.3.9600 / x64

    Would be good to have some videos on this subject

    • bhawna

      Hello Carlton,
      The latest Canary links are mentioned in the post. One thing to note is that currently Examples can only be added to requests that are saved inside a collection. Hope this works for you!

  • Kyle Jepson

    Hello,

    I have tried to download all versions of postman (windows, mac, chrome) and I do not see examples in any of these.

    Can you confirm if this needs to be enabled on our PRO account? Or is this intended to show a feature feature?! This is exactly what my frond end team needs right now so I have spent all day trying to figure this out.

    • bhawna

      Hello Kyle,
      Sorry for the confusion around this. Examples are NOT out in production yet. However, you can get early access by downloading the latest Canary version (links mentioned in the post), and do let us know your feedback 🙂

  • Stephanie

    Hi,

    I am a little disappointing that at the end it is "just" used for the documentation.
    Do you have any plan to extend these examples with a Test tab?
    To fully test an API you have to test all the cases so it would be nice to have for each couple params/response we can also associate the tests that will go with that.
    Thanks for giving me your thought on that

    Stephanie

    • bhawna

      Hi Stephanie, yes – ability to add tests and send examples as requests is a part of our roadmap. Stay tuned for latest updates on this! 🙂

  • andres

    Thank you very much for your great work!

    The next cool feature should be creating random mock messages based on a json schema and values based on regexp

    • bhawna

      Thanks Andres. We've noted down your suggestion 🙂

  • Deano

    Great feature! Will we be able to create Tests for each Example in the future?
    Thanks, great work all.

    • bhawna

      Hi Deano, yes – ability to add tests and send examples as requests is a part of our roadmap. Stay tuned for latest updates on this! 🙂

  • ulysse

    Hello, I can't see the status code of an example in the doc. I can see Sample Request and Sample Response but the latter is only the body, without status code. Am I missing something ?

    • bhawna

      Hi Ulysse, the status codes which you set for your examples are currently NOT shown in the documenter. However, you can specify those in the example name for now. For instance, you could name your example as '200 OK example' or '400 Error' – these will be displayed in the documenter and will make your examples more consumable 😀

  • Anthony Huerta

    I followed the page directions http://blog.getpostman.com/2017/03/16/simulate-a-back-end-with-postmans-mock-service/ to create a mock response and I am getting this error. {
    "error": {
    "name": "mockRequestNotFoundError",
    "message": "We were unable to find any matching requests for the mock path (i.e. undefined) in your collection."
    }
    }

    • bhawna

      Hi Anthony, so sorry for the delay in getting back. Could you send us an email to help@getpostman.com please? We'll be able to look into this in more detail. Thank you.

  • Vipul Chaudhary

    The button "Save Example" is greyed-out for me.
    I am trying to save an existing response, I have specified a name of the example, even tried to change the response status code and data, still I don't get an option to save.
    My request is also a part of a collection.

    • bhawna

      Hi Vipul, sorry to hear that. Could you send us an email to help@getpostman.com along with a screenshot please? Thank you.

  • Can

    Hi,
    I used your mock server and i like it, it is super easy to use, thank you for the product.
    I want to use your product but i stuck somewhere.
    For example,
    1- there is a list service with pagination and Params does not work. Params are ignored by mock servers. I wish to create multiple mock examples for '?page=1', '?page=2' etc., and their custom responses in examples section, then when i request to mock server with that params, i want that responses.
    2- and also with post services need this too. save endpoint; 'saveItem'.
    POST '/save' endpoint and multiple example request bodies;
    '{ responseWith: balance }', //returns with Balance body you defined in example 1
    '{ responseWith: itemName }', "returns with Balance body you defined in example 2

    So one endpoint can have multiple 200 responses with custom params and request body. (also can have multiple 400 errors too)
    If you improve your mock servers to work this way, this would be awesome.

    • bhawna

      Hi Can, thanks for writing in. Could you send us an email to help@getpostman.com elaborating your use case a bit more? We'll be able to look into this in more detail. Thank you.

  • bharadwaj

    I've been waiting for this feature, we used to do maintain different requests earlier, now it saves our time, nice.
    Thanks, PostMan team.

  • Tom Somerville

    Hi,

    I do like this feature and I think with some additions postman can have a superior product over something like apiary, however for that to happen we would need some key features added:

    * To be able to add description text for each request
    * To be able to describe each of the attributes of a request
    Something like:
    <attribute: string
    3 character ISO-4217 code for the currency being used for the transaction (eg. USD, EUR, JPY).
    * To be able to add description text for responses as well

    • bhawna

      Hi Tom,
      Thanks for the suggestion. Quick clarification – are you talking about having descriptions for example requests and responses? Postman already supports request and attribute level descriptions.