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":
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":
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:
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:
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!
Saturday, September 14, 2019
I've moved! I've really enjoyed using Blogger for my blog, but it didn't integrate with my website in the way I wanted. So I...
This week, we'll be talking about adding assertions to our Postman requests. In last week's post , we discussed what various API re...
As software becomes increasingly complex, more and more companies are turning to APIs as a way to organize and manage their application'...
Two weeks ago, I wrote about my first experiences using Cypress.io. I was intrigued by the fact that it was possible to do http requests us...