Learn from experts and connect with global tech leaders at POST/CON 24. Register by March 26 to save 30%.

Learn more →
X

Mock Responses in Postman by Using Examples

Avatar

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!

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. 

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.

Comment

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.

44 thoughts on “Mock Responses in Postman by Using Examples

  • Avatar

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

  • Avatar

    Great! I love that, thank you very much for listen to developers and to do possible this changes, this proyect. Amazing

  • Avatar

    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?

    • Avatar

      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 🙂

  • Avatar

    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

    • Avatar

      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!

  • Avatar

    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.

    • Avatar

      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 🙂

  • Avatar

    and find it in windows app ^_^ finally

  • Avatar

    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

    • Avatar

      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! ?

  • Avatar

    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

    • Avatar

      Thanks Andres. We’ve noted down your suggestion 🙂

  • Avatar

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

    • Avatar

      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! 🙂

  • Avatar

    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 ?

    • Avatar

      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 😀

  • Avatar

    I followed the page directions https://blog.postman.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.”
    }
    }

    • Avatar

      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.

  • Avatar

    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.

    • Avatar

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

  • Avatar

    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.

    • Avatar

      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.

    • Avatar

      +1000

  • Avatar

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

  • Avatar

    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

    • Avatar

      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.

      • Avatar

        Postman doesn’t support response attribute level description

  • Avatar

    Sorry to be a downer, but this has killed Postman for me. I’ll try to explain why, as this is intended as constructive feedback.

    I use Postman to test responses from 3rd party APIs, usually where there are a bunch of security parameters that have to be submitted with each request.

    I put in all the params and get the first request working.

    Then I change the url for the next request and add/remove/tweak any additional params, hit Go and check the response. Repeat till I’m done.

    This feature seems to have removed my ability to use Postman in this way.

    Unless of course I’m missing something? Any pointers would be appreciated.

    Hope it’s useful. I used to love using Postman, and I’d really rather not start using an alternative.

    As I said, it’s intended constructively

    • Avatar

      I have NO idea how this feature has anything to do with the way you use Postman. This is useful for people who export Postman collections for Docs and are using the test features of the App. This does not disrupt the way you are using Postman. This is just a convenient way to save responses, if that is useful to you.

      • Avatar

        I know – it seems nuts -, but ever since this new feature came in, I can’t find the way to use Postman the way I was using it before.

        Could be me being dim, but I came back to it a few times over a few weeks and still couldn’t work out how to just post queries to (someone else’s) 3rd party API and read the results

        Now I just do everything from a terminal. Clunky, but it gets me there.

        • Avatar

          Wait, was was “removed”? Does something not show up anymore that should?

  • Avatar

    I just hope I can change the order of the examples.

  • Avatar

    I want to get different result from same endpoint. I this possible?

  • Avatar

    how to keep backup of saved examples?

    • Avatar

      If you create a Postman account (https://www.postman.com/), your saved examples will be synced with your account.

  • Avatar

    Is it possible to reorder the examples after creating them? I use the examples to show multiple ways of using an api endpoint including various success and error responses but the examples only show in the order they were created in, and the default in the published documentation only shows the first one that you added. Reordering them would allow me to make the reading experience in our published docs better by having a consistent order in the examples without having to delete them all and recreate them again

  • Avatar

    If an env variable is saved with initial value as 10 and current value is saved as 100, then if I try to fetch the value of the variable in the scripts, I get the current value but when I use {{variable_name}} in the mock response, I get the initial value. Why is this so? How to get the current value of the variable in the mock response as well?

  • Avatar

    does Postman support returning different examples(on the same endpoint) by using different conditions(e.g if(myheaderlist contains abc) {return example 1} else return example 2 ?

  • Avatar

    בס”ד
    Hi all, Is there a way to call a collection/ request (as private) one and call it from a different collection (as a public) like pointer? this will make maintenance easy. Thanks