What I Learned at POST/CON Part I: Examples and Mocking

I've just returned from POST/CON, the annual Postman users' conference, and I am so excited about everything I learned there!  So excited, in fact, that I'm going to devote not one, but TWO blog posts to sharing my findings.

If you aren't already using Postman for your API testing, why on earth not?  It's the best API testing tool out there!  My opinion was reinforced this week, when I learned just how easy it is to create API examples and mock responses.  I'll be teaching you how to do both things in today's post.

The instructions in this post will be for the free version of Postman, and I'll be using version 7.  Your results will look slightly different in version 6; and the Pro version of Postman will have more functionality for the documentation and mocks than will be described here.

First, examples: why would you want to create an example of a request?  Because it's a great way to show other people on your team how the request is supposed to work.  It can also be used to create documentation for your API. 

The request I'll be using for today's post is one of the GET requests from Mark Winteringham's wonderful API, Restful-Booker.  Here is the request and the response:

You can see that this is a GET request that is asking for the booking with the ID of 1, and that the response returns the booking with the first and last name, checkin and checkout dates, and other details. 

If we wanted to teach someone else on our team how this request works, we could simply share this request with them.  But- what if the API is still being created and doesn't work yet?  Or what if our teammate doesn't have the correct authentication access to the request, and can't run it?  We can show them exactly what's supposed to happen with the request by creating an example.  In the upper right corner of the Postman window, just underneath the environment dropdown, is a link that says "Examples":

Click on this link, then click "Add Example".  A new request tab will open up with the same name as the original GET request, prefaced by "e.g":

The request will already have the HTTP verb, the URL, and any headers or request parameters set.  All you need to do to finish the example is to paste in an example of what the request response should be:

and set the appropriate response code:

Save the example, and return to the original GET request.  You'll see that now there is an example request listed in the top right:

Now anyone who sees the request can click on the Examples link to see exactly how the request is supposed to behave. 

Examples are also great for showing how an API request should behave in negative scenarios, such as when an id is not found, or when a user is not authenticated.

Another great feature of examples is that you can use them in your documentation.  You don't need to have examples to create documentation, but it makes your documentation much easier to understand.  To create documentation in Postman, you need a collection with requests.  Click on the three-dot menu beside the collection, and choose "Publish Docs":

A "Publish Collection" web page will open.  Select an environment if you like, and click the Publish Collection button.  Once published, you'll see a URL that you can go to view your documentation.  Go to that URL, and you'll see your request with your example response!

You can also use your example requests to create a mock server.  This can be used whenever you don't have access to the actual API server, such as when a feature is still being developed or when you are doing contract testing with another API. 

To set up a mock server, simply click on the three-dot menu beside the collection name and choose "Mock Collection".  You'll be presented with a pop-up window like this:

Give your mock collection a name, and click the "Create mock server" button.  You'll be assigned a special mock server that looks like this: https://<some guid>.mock.pstmn.io. 

This mock server is designed to return the response you created in your GET example whenever you make a request with an endpoint that matches the GET example.  Copy the URL for the mock server and paste it in a GET request, and then add the appropriate endpoint for your example: /booking/1.  Click send, and you should get this response:

Now you can save this request, naming it something like MOCK Get Booking, and you can save it to a collection called something like MOCK Restful Booker. 

You can create examples and mock requests like this for every request in an API, and when you have finished, you will have a complete documentation of your API as well as a mock server that will allow you call an API and get an appropriate response without actually connecting to the API's server!

I hope you find this helpful in your work with APIs.  Next week, I'll have more great knowledge from POST/CON to share!