Last time, we signed up for Postman, logged into the web portal, and issued a simple GET request to the NHL API for Teams info. This time, we’re going to learn to set some Parameters and configure our client to send credentials to the server for authorizing our access to an API.
Remember in the last blog I mentioned that entering a URL into a web browser and hitting go is making a GET request?
We’re about to build on that. I use Bing. (Make your jokes now.) The parameters we send to this API are our search terms. Let’s say I want to request information on “Carolina Hurricanes” I could go to bing.com and fill in those terms to get results.
When we hit enter, we see our results.
Look at the URL, and you can see the GET request you just made.
The base URL for a search is http://www.bing.com/search. Our parameter name is q (aka query), and our parameter value (sometimes called query string) is carolina+hurricanes. Knowing that, we could search for anything we want, by putting our search terms right into our query string. So if you wanted to search for our newest goalie Alex Nedeljkovic, you could make a GET request to https://www.bing.com/search?q=alex+nedeljkovic.
Now, let’s take what we’ve learned and pass a teamId parameter to the NHL teams request. Yes, you had to know what the parameter name was before you can use it. Luckily, I’d already discovered that before, so we can start using it here.
We could type it right into the URL https://statsapi.web.nhl.com/api/v1/teams/?teamId=12. When we do that, we’ll see that Postman recognizes the fact we passed a parameter in the URL, so it will show us that in the Params tab.
Now, when you hit Send, you only get one team back, the one with team id 12.
Oh look, it’s the Carolina Hurricanes!
You could also have plugged parameters directly through the Params tab. Let’s add a parameter that will add the current roster to the results. The parameter’s name (KEY) is “expand”, and the value is “team.roster”.
Now, if you’re dealing with a request type other than GET, you have to type all your parameters in through the Params tab (the middle section of the image above). The great thing about the params tab is that any URL encoding for your value is taken care of for you. No need to go look up the encoding for symbols!
Passing Authorization Credentials via Postman
It shouldn’t be too long after you start working with APIs, that you’re going to have to pass some credential showing you are authorized (auth|authed) to make a given API call. From what I’ve seen, Postman makes this pretty easy.
Every request you make via Postman has some form of auth, even if that auth is “No Auth” or anonymous. Click on the Authorization tab for our last request.
It’s set to Inherit Auth from Parent. On the right, it’s helpful enough to tell you what this request’s parent is: NHL Demo. You can click on the link, NHL Demo, and it takes you to the collection’s Auth page.
You can see the default for this collection is set to “No Auth” so we’re running anonymous. If you are dealing with an API that requires auth, it’s easiest to set your credentials (creds) here, rather than for each individual request. Keep in mind, there are some unruly APIs that have some requests that must be authed, and some that allow anonymous.
Super simple auth
There are some APIs I’ve dealt with that have such simple auth you can use the old username:password@url in order to authenticate. If you have to pass credentials, and the API owner says they have basic auth, it may be worth it to try this super simple auth to see if your requests go through.
Slightly more complex auth
I’ve also dealt with some APIs that are on Microsoft’s Active Directory. In those cases, I’ve been able to use “Basic Auth”. With this, you can send your username and password in a slightly more secure way than plain text on the URL.
I pulled this example from another project I’m working on. This is from the desktop client. Simply fill in the username, this username can be domain\username, username@domain, or just username depending on your need. Fill in your password. You can even tick show password if you want to double-check your typing.
Once you’ve saved your changes, you can click Send, and your creds are passed along with your request. I’m not including results here, since I’d have to cover them in red. Take my word on it, results came back from the above request.
The next type of Auth you’re likely to encounter is API Key auth. If your API supports this method, you will usually get it when you sign up to use the API. It’s often found in your user account settings with that API provider. It’s often a hash string that ends with ==. It doesn’t have to, it can be anything your API provider decides it should be.
The only thing to really worry about with a key is do you send it in your headers (think old school HTTP Headers) or Query Params (your url string). More often I see the key being passed over the Header than in the query string. Once you save your key creds, it’s sent along with your requests.
If you get failures when using key auth, first double check the value, then the Add to field, then look at the request type (GET vs POST). One of those three will usually get you going again.
Other Auth Types
If you have to use one of the other auth types, reach out to a programmer for help. If they’ve dealt with APIs before, they can usually get you going pretty quickly. Especially if it’s one of those OAuth deals. You may hear OAuth referred to as a three-legged dance.
Yeah, it’s like that. Pretend you have three legs.
Now, try to dance.
Not easy, is it?
These two articles cover most of my API usage. Once I can pass my credentials and parameters, most of my time is spent doing analysis and data engineering. There’s plenty more you could do in Postman, but I haven’t needed those features yet.
If you do have any API or Data Engineering questions, please hit me up on twitter @shannonlowder.