This post started as a tweet From @MMarie, suggesting someone blog about getting started with Postman. I guess I’m lucky I spent so much time with devs who were building application programming interfaces (APIs) on top of databases I was building. I got to know the lingo and technology behind APIs. This early exposure to APIs helped me later when I had to learn how to use APIs as a data source in some of my data engineering projects. The next few blog posts here are meant to help you get started with Postman and APIs too.
First, some terminology
Think of an Application Programming Interface (API) like a menu. That menu provides a list of all the dishes a restaurant offers. If you’re lucky, that menu has descriptions of the food. What’s important is you get a list of things you can get. It doesn’t give you the recipe, or detail how the food will get to you after you’ve ordered a dish. You just know what you can request.
An API is a list of operations you can consume from a given source. You may get a description of what these operations do, along with a list of parameters and outputs, if you’re lucky. Much of the time I’ve spent with APIs as a source, I’ve had to discover what operations were available, as well as the structure of the output. The benefit to the API is you can use it to perform work for you, without recreating that code. Simply call it from your program and move on.
While an API can be created on top of some hardware, the APIs I consume are often hosted on a web server in some form. This form could be a physical server, a virtual machine (VM), or it could be a web service. In Azure, we’re talking about App Services, Containers, or Functions. Generically, these are referred to as hosts.
Clients or consumers are simply a program that consumes a given API. In this article, our consumer is going to be Postman. It’s a highly capable client that helps you explore the API while you build another client that will eventually become part of a data pipeline.
Requests are what you send to the API to make it perform a given operation. The three most common requests are GET, POST, and DELETE. These three are pretty simple. GET is for retrieving data. POST is sending new data to the service. DELETE is a request to remove some data. These aren’t hard rules, because an API developer could always choose to make all requests a GET, or the developer could choose to use a GET request perform a delete.
You can get Postman as a web client or a thick client. If you’re working with a client where you are not allowed to install software, or if you’re just looking to dabble, start with the web version. You may hit one of a few limitations in that version. But with simple enough testing, it’ll be sufficient. For this demo, I’m going to stick with the web client. In later entries, I’ll switch over to the thick client. The thick client is available for Windows, Mac, and Linux!
When you get to the web portal, you will have to sign up for an account.
No worries, it’s free!
When you log in, you’ll land here.
I’m going to use the NHL official API for my demo, since that’s one I’m using for other demos right now. I’ll start by clicking “Start with something new”.
I like to keep my testing organized by API. To do that, I create Collections. Click the + symbol to the right of Collections, and choose New Collection.
Give you collection a name. Mine will be “NHL Demo”. We’re going to start making some requests next. But first, there is no official documentation for this API. Just a bunch of us fans exploring the API, trying things until they break, and documenting what we find. Right now, the search engine of your choice will help finding a guide. The base URL is https://statsapi.web.nhl.com/api/v1/. We’re going to start by requesting a list of teams. We can get that by requesting a GET of https://statsapi.web.nhl.com/api/v1/teams. Click that link… when it opens you’ve now sent a GET request using your browser. Now, lets do the same thing using Postman.
Click the down arrow to the left of your new collection name, it will reveal a menu entry to “Add a request.”
After clicking “Add a request” you’ll get a new page to the right of your Collections list. Give your new request a name. I’m calling mine “GET Teans”. If I’m going to make multiple requests of the same resource to try out different parameters, then I’ll often add more description and a timestamp yyyymmdd-hhmmss to tell them apart.
You’ll also want to paste in the URL https://statsapi.web.nhl.com/api/v1/teams to the right of GET. Then hit Send.
Notice the results returned are the same as you saw in your web browser. That’s because both clients issued a GET command. Think about that a second, because that’s an important point. The request you perform every day when you type a URL into your web browser is an API request to some web server to GET you some data.
The only difference between the call we made to the NHL API and the one you make to say Google, is the Google “API” returns results in HTML (XML) and the NHL API returns JSON.
Realizing that opens possibilities for future use in Postman.
In my next entry, I want to dive in to the different options we can set for our requests. I’ll cover Parameters and Authorization, the most common two options you’ll have to adjust in order to make many of your API requests.
In the mean time, if you have any questions, hit me up on twitter @shannonlowder.