The structure of an API request
The request tab in Postman provides a lot of information about the various pieces that make up an API request. Each of these pieces plays an important part in sending and receiving data with an API, and so I will walk you through each one in turn. Some parts of an API request are optional depending on what kind of request it is and what you are trying to do with it, but there are two pieces that are required for every API request. Every API request needs an endpoint and an action.
API endpoints
Every web-based API request must specify an endpoint. In the Postman requests tab, you are prompted to enter the request URL. Postman is asking you to put in a URL because an API endpoint is just a URL. We use the term URL so much that we can sometimes forget what it stands for. URL is an acronym for Uniform Resource Locator. The endpoint of an API call specifies the resource, or the "R" of the URL. In other words, an API endpoint is the uniform locator for a particular resource that you want to interact with on the server. URLs help you to locate resources on a server, and so they are used as the endpoints in an API call.
Fill in this field in the requests tab by typing in the following URL: https://api.github.com/users/djwester/repos. This endpoint will give you information about my repositories on GitHub. If you have a GitHub account of your own, you can put in your username in the part of the URL where it says djwester and get back data for your own repositories.
You will often see an API endpoint specified without the base part of this API. So, for example, if you look at the GitHub API documentation, it will report the endpoint for this as /users/:username/repos. All the GitHub API calls start with the same base URL (in other words, https://api.github.com), and so this part of the endpoint is often left out when talking about an endpoint. If you see API endpoints listed that start with a / instead of with http or www, just remember that you need to go and find the base API URL for the endpoint in order to call it.
API actions
Every API call needs to specify a resource that we are working with. This is the endpoint, but there is a second thing that every API call needs. An API needs to do something with the specified resource. We specify what we want an API to do with API actions. These actions are sometimes called verbs, and they tell the API call what we expect it to do with the resource that we have given it. For some resources, only certain actions are valid, while for others there can be multiple different valid API actions.
In Postman, you can select the desired action using the drop-down menu beside the textbox where you entered the URL. By default, Postman sets the action to GET, but if you click on the dropdown, you can see that there are many other actions available for API calls. Some of these actions are specialized for particular applications, and so you won't run into them very often. In this book, I will only use GET, POST, PUT, and DELETE. Many APIs also use PATCH, OPTIONS, and HEAD, but using these is very similar to using the four that I will use, and so you will be able to easily pick up on how to use them if you run into them. The rest of the actions in this list are not often used and you will probably not encounter them much in the applications that you test and create.
The four actions (GET, POST, PUT, and DELETE) are sometimes summarized with the acronym CRUD. This stands for Create, Read, Update, and Delete. In an API, the POST action is used to create new objects, the GET action is used to read information about objects, the PUT action is used to modify existing objects, and (surprise, surprise) the DELETE action is used to delete objects. In practice, having an API that supports all aspects of CRUD gives you the flexibility to do almost anything you might need to, which is why these four actions are the most common ones you will see.
API actions and endpoints are required for web APIs, but there are several other important pieces to API requests that we will consider.
API parameters
API parameters are used to create structure and order in an API. They organize similar things together. For example, in the API call we are looking at, we are getting the repositories for a particular user in GitHub. There are many users in GitHub, and we can use the exact same API endpoint to get the repository list for any of them with the change of username in the endpoint. That part of the endpoint where it accepts different usernames is a parameter.
Request parameters
The username parameter in the GitHub repositories API endpoint is known as a request parameter. You can think of a request parameter as a replace string in the API endpoint. They are very common in web APIs. You will see them represented in different ways in the documentation of different APIs. For example, the GitHub documentation uses a colon in front of the request parameter to indicate that it is a request parameter and not just another part of the endpoint. You will see endpoints specified like this in the GitHub documentation: /users/:username/repos.
In other APIs you will see request parameters enclosed in curly braces instead. In that case, the endpoint would look like /users/{{username}}/repos. Whatever the format used, the point of request parameters is to get particular information about different objects that are all the same type. We have already seen how you can do that with this endpoint by replacing my username with your username (or any other GitHub user's name).
Query parameters
There is another kind of parameter that you can have in an API endpoint. This kind of parameter is known as a query parameter and it is a little bit trickier to deal with. A query parameter often acts like a kind of filter or additional action that you can apply to an endpoint. They are represented by a question mark in the API endpoint and are specified with a key that is the item you are querying for, and a value, which is what you want the query to return.
That's all very abstract, so let's take a look at it with the GitHub request we have open. This endpoint supports a couple of different query parameters. One of them is the type parameter. In order to add parameters to an API endpoint in Postman, make sure you have the Params tab selected and then put the name of the query parameter into the Key field and the value into the Value field. In this case, we will use the type parameter, so enter that word into the Key field.
For this endpoint, the type parameter allows us to filter based on whether you are the owner of a repository or just a member. By default, the endpoint will return only those repositories that you are the owner of, but if I want to see all the repositories that I am a member of, I can put member in the Value field for this. At this point, the request should look something like this:
Figure 1.5 – Query parameter type in an API call
If I send this request, I get back all the repositories that I am a member of, as opposed to the ones that I own. Parameters are a powerful API paradigm, but there are still a few more fundamental pieces of the API structure that I haven't talked about yet. The next thing we will look at are API headers.
API headers
Every API request needs to include some headers. Headers include some of the background information that is often not that important to human users, but they help the server have some information about the client that is sending the request. Sometimes, we will need to modify or add certain headers in order to get an API to do what we want, but often we can just let the tool that we are using send the default headers that it needs to send without worrying about it.
In Postman, you can see what headers will be sent with your request by using the Headers tab. You can also modify the headers and add additional ones here as needed. I will get into more details on how headers work and how to use them in future chapters, but for now, you don't need to worry about them too much. The point of mentioning them here is just to make sure you know the terminology. Let's turn our attention instead to the body of an API request.
API body
If you want to create or modify resources with an API, you will need to give the server some information about what kind of properties you want the resource to have. This kind of information is usually specified in the body of a request.
The request body can take on many forms. If you click on the Body tab in the Postman request, you can see some of the different kinds of data that you can send. You can send from-data, encoded form data, raw data, binary data, and even GraphQL data. As you can imagine, there are a lot of details that go into sending data in the body of a request. Most of the time, GET requests do not require you to specify a body. Other types of requests, such as POST and PUT, which do require you to specify a body, often require some form of authorization since they allow you to modify data. We will learn more about authorization in Chapter 5, Understanding Authorization Options. Once you can authorize requests, there will be a lot more examples of the kinds of things you might want to specify in the body of an API request.
API response
So far, we have spent a lot of time talking about the various pieces that make up an API request, but there is one very important thing that we have been kind of ignoring. An API is a two-way street. It sends data to the server in the request, but then the server processes that request and sends back a response.
The default view that Postman uses displays the response at the bottom of the request page. You can also modify the view to see the request and the response in side-by-side panels. You can change to this view if you so wish by clicking on the Two pane view icon at the bottom of the application, as shown in the following screenshot:
Figure 1.6 – Switching views
There are a few different aspects to the response. The most obvious one is the body of the response. This is usually where most of the information that you are looking for will be included. In the GitHub repositories requests that you have made, the lists of repositories will show up in the body of the response, and Postman will display them in that tab.
An API response can also include a few other things such as cookies and headers. These kinds of things can be very important hints as to what is going on when testing or creating APIs, and I will talk about them more as we go through the book
We have covered a lot of ground when it comes to how APIs request work. We have seen how an API request can have a lot of different pieces to it. These simple pieces all come together to create a powerful tool. You now have a grasp of the basic pieces that make up an API call and how to use them in Postman. It's almost time to talk about how to use this to test APIs, but before we get into that, I want to pause for a minute so that you can put into practice all this theory I've just gone over.
Learning by doing – making API calls
Books are a great way to grow and learn. You are reading this book, so I don't think I need to convince you of that! However, reading a book (or even three or four books) on a topic does not mean you understand that topic. There is theory and there is practice. There is knowing something that you've read and knowing something that you've done. These are two very different things, and if all you do is read about a topic, you will feel like you know that topic, but that will be more of a feeling than a reality. This book is a hands-on guide, and my purpose in writing this is to help you improve your skills around API testing and to give you a deep knowledge of how Postman can help you understand API quality.
If you want that to be a reality and you don't just want this book to be another piece of theoretical knowledge bouncing around inside your head, you need to put into practice the things that you are learning. I know it's hard when you are reading a book. I personally find it difficult to interrupt the flow of a book that I am reading in order to do exercises. I get it. It feels like you are slowing down your learning. This isn't a book on the theory of how we learn, but please believe me when I say that you will learn a lot more if you pause along the way and work through practical examples related to what you have just been learning. I will include those throughout this book and encourage you to work through them. As with any learning project, you will get out of it what you put into it. Take that time to do the exercises.
OK. With that out of the way, let's look at an exercise that you can do to help make all this theory about the structure of an API request stick. I will call this exercise "Map the app" – a nice catchy title, right?
Map the app exercise
The purpose of this is to help you cement what you have learned about APIs and to make sure you know how to call them. For this exercise I want you to map out the API of an application. If you have one that you are currently testing – great, use that! If not, you can find a simple public API on the internet. You can find a list of some of the public APIs here: https://github.com/public-apis/public-apis. Pick a simple API from that list (the Cat Facts API, for example). Make sure that you pick one that does not require authorization.
When I say map your application, I'm not talking about a cartographic map. I am talking about something like a line diagram linking different parts of the application together, or even a mind map or a list of different parts of the application. What I want you to do with this exercise is this:
- Try calling some of the different endpoints of the application and write down some observations about what they do and how they relate to each other.
- See whether you can map out what the API lets you do and how the different parts relate to each other. You can do this by creating a list of the different endpoints.
- Create a collection in Postman and see whether you can organize the different endpoints within that collection.
- Explore the different options in the API and get some practice calling API endpoints!
As you complete this exercise, take a bit of time to reflect on what you have learned and what you are already able to do. You can make API calls and do some investigation to dig in and understand how an API is put together. This is a great start and I will continue to expand on what you know as I walk you through some considerations for API testing.