Chapter 2 - Exploring APIs with Postman
Overview: In this chapter we will go over how to install Postman, how you can create requests or import them from other sources, and how to organize your requests in collections.
For maximum learning experience, please view the course video for dynamic demonstrations.
So now that we've talked about what APIs are and we've looked at how we can explore them in websites and mobile devices, let's look at a tool that will help you really play with APIs and explore what they can do and what they can't do.
So the tool we're going to be going over is Postman, which is really the best REST client on the market today. To install it go to [www.getpostman.com/apps](https://www.getpostman.com/apps.
Once there, choose the correct executable for your platform, download it and it will install very easily.
Once you open Postman, you'll see a form for entering URL and parameter information. For example, if I type in this URL http://worldtimeapi.orgfor getting time zone information and I press send, I get this list of time zones
Then if I take my own time zone, put it in and now I get the time information. So this is an API that's available for getting the time and we can access it through Postman.
So once I do that, I can go to history. I can open up previous requests and send them again. I can see what happens if I do something a little different, see what the errors are. I have the status information, the size of the download, the amount of time it took, all the information I need to better understand my API.
So that's the most basic functionality of Postman.
Now that we've done some basic data entry, let's combine Postman with the web developer tools we were looking at before. Here we are on the Amazon site. We have our completion requests and so we just have to select one, right click to bring up the context menu and do “Copy as cURL” (or on Windows, “Copy as cURL (bash)” and this works the same in both Firefox and Chrome.
So I've copied it as cURL and I go back to Postman and I import. It looks like the button's disabled, but it's not. Import, paste raw text, and I paste it in and then I import and now we have it here in Postman, the very same request.
If we send it we can see that it's working like the one on the website. I have all these suggestions for things that start with, in this case “C”, because that's our prefix and we can unclick things and see if it still works. You'll see that these are query parameters, meaning that they're tagged on the end of the URL.
When we're getting information through an API, when we're doing “GET,” the parameters are often passed as part of the URL as query parameters. So we can remove them here, and you can see that they are disappearing as I unclick and then we can send again to see if it works, and it's still working.
So after some experimentation I can see that only three of these parameters are actually necessary to make the request work the way we want it where it's returning suggestions. And although it only has these three in the URL, we still have a little bit of clutter here with our things that we don't want. So we can bulk edit. You can see here they are here, and we can just get rid of these. Save again and now we have a nice clean URL and parameters that we can experiment with more completely, and it's still working.
So that's using Postman with a GET API that's just getting information, but what if we want to actually do something with our API that's changing things on the server?
That's going to happen through a POST request and let's look at an example of getting that from the browser. So we come back here to Firefox and now I'm at the [Big Fish Games website] (https://www.bigfishgames.com/) and I'm going to sign in. So now I'm going to sign in and when I press sign in, oh I have to clear my filter and here it is. It's a POST request this time because we're actually doing something not just getting information. So let's go ahead and copy as cURL and into Postman.
Here we have our API service living here at [susi.bigfishgames.com] (https://susi.bigfishgames.com/) and this is the endpoint, sign in because we're signing in with an existing account. Here's the body of the request. This time it's not in the URL, it's part of a form. So it's saved here as
form-urlencoded and when we send this ...
Oops, we have a little issue where we have double encoding:
So the encoding is because certain characters can't be sent through the browser, they have to be changed into a special encoding. So the at sign (@) is one of those characters, and it's code is %40, but we're going to change it back to an at sign (
email@example.com) and then we'll try this again.
All right, so now it worked and we can see the response. We have our user email, and the use her name and this is the token that we got back. So this is how we can do a post request with Postman.
**So the final resource I want to look at in this section is the Restful Booker API Playground. **
So this was created by Mark Wintringham, and it's at restful-booker.herokuapp.com
Restful-Booker is a resource, it's a very simple API, it has some bugs already built into it and it's really great for practicing your API testing techniques.
If we come here to the API docs, we can see that it's very well documented, and again we have our little cURL request. So this is going to make it quite easy for us to create a collection of Restful Booker API calls that we can then in future lessons do our test passes on.
Once again we're going to Copy as cURL and put it into our Postman. Import here, and now we have our authorization request with our username and password. We're going to save this to a new collection. Let's just create a new collection here. We'll call it “Restful Booker” and now we can save this as “Auth” in Restful-Booker, and here we go. We're starting to build our broad collection.
So I've gathered all the requests from Restful Booker into our Postman Restful Booker collection along with the auth requests. We have several varieties of GET requests, which are getting by the name or the date or the ID. We have a POST request to create a booking. We can update a booking, either with the full booking information or with partial booking information, and we can delete.
You'll see that we have headers as well. If you recall, we have this Auth, this very secure Auth which will give us this token in response. Tis token is actually what is going into the header information. We haven't done much with headers, but here we can see that there's this cookie header that wants this token. So if we just try to do this with the default (
token = abc123) it'll say it's forbidden, but if we put in the token for our Auth, now it works.
The POST request is creating a new thing, and the response is going to be different every time because it's returning a different ID. Let's look at how that's gonna work.
We'll change the name a little bit. So here we have this one coming back as 13, 14, 15. So we're actually creating resources, whereas with updating we can do this again and again and the response is always going to be the same because we're updating the same resource. So every time you send this response you can send it multiple times and always get the same response back, whereas with a POST you send it multiple times, you could get a different response back.
Iif you'll notice for a PUT, we need to have the whole object passed in just to change the name, but for a PATCH we can just input the things that we want to change. So here again, and it returns the entire object this time with just what we wanted changed and then DEL is going to delete the object altogether.
The great thing about this playground is that it refreshes itself every 10 minutes. You don't have to worry that you're breaking anything that people are actually counting on to work.
Now that we have a collection, we can save our collection for later. We can export it. This is just going to export it as a json file and now we can share it with our coworkers or whatever and they can very easily import it into their own collection. So we can choose the file. Here it is, and we'll just import it as a copy. Once you've done the work of creating these collections, it's very easy to share them with your team and that makes collaborating on the APIs very easy.
Now that we've gone over the Postman tool and how to get information into the Postman tool and play with that information, we're ready to start really testing our APIs.