For a long time now, I’ve been an avid user of Postman - An incredibly useful tool that makes it simple to try out different HTTP requests via a GUI.

Although I’ll often interact with APIs with code, Postman plays a big part in the initial discovery and testing of said API before I get to deep into something.

So, for this post - I am going to pick a couple of public APIs and walk through how you can use Postman to learn more about what an API can do.

APIs

Before we dig into which APIs we will look at, it’s probably worth clarifying what an API is.

An API, or Application Programming Interface, is something that sits between an application, client or user and the application’s backend. APIs can be incredibly simple or massively complex - there is no hard or fast rule on this. The simplest way to break it down is that an API provides you with a way to interact with a platform/service/software’s capabilities and data through various means.

APIs are not exclusive to the web - Take iOS or Xbox Development for example. Developing for either platform involves heavily interacting with each platforms API. An iOS app that would like to provide a user with a way to upload or edit photos within a users Camera Roll might use the iOS PhotoKit API to do so. Telling a user they’ve unlocked an Achievement or that a Game session is ready within an Xbox game will use the appropriate system APIs to that too.

Not all APIs are web-based, but so (so!) many of them are. In the world of Cloud, most APIs we use to complete different interactions are web-based. The most common (but not only!) format of web API is a REST API. REST APIs are just a standard way of designing a web-based API that follows a set of rules. These rules define what the API can do, how it does what it can do and how you should Authenticate yourself with said API.

REST is HTTP based. You interact with features of an API by sending an HTTP POST/GET/PATCH/PUT (etc) request to the API, with the appropriate data the API expects and in return, the API should perform the desired action and return you desired data.

There are loads of REST APIs on the web, such as:

In this post, we are going to pick 2 APIs to play with, one of them requires authentication, the other doesn’t. Overall, the process of learning and playing with any API is the same - so hopefully you’ll see that going forward.

Our APIs for this post will be:

Postman

Postman is a fantastic tool for performing HTTP/HTTPS requests. It allows you to build up a request as if you were a web user but allows you to see how a website reacts before coding up the result later. I use this a lot when interacting with APIs as it is a quick and easy way to see what I should be getting back assuming my request is valid.

Postman API Client is available here. Download and install it and once you are set up, signed up and signed in - you should see something similar to below:

Once you get set up, we are good to get cracking.

Chuck Norris Facts

First of all, what a great idea! The Chuck Norris Facts API is a long-time favourite of mine. It lets you get random facts about Chuck Norris and even better, it lets you substitute Chuck Norris for a custom name!

Like any good API, we start by looking at its documentation.

Hop over to Chuck Norris API and take a look at what we get.

This page clearly states what features it has, what endpoint you need to access to get said feature, what data (if any) you need to send to the feature endpoint and most importantly, what HTTP request type you need to send.

Along with what and how it also shows examples of what you should expect back.

Let’s translate the first example into Postman

Retrieve A random Joke in JSON

GET https://api.chucknorris.io/jokes/random { "icon_url" : "https://assets.chucknorris.host/img/avatar/chuck-norris.png" , "id" : "XGxNDAPNQniLF41QxPv_9Q" , "url" : "" "value" : "Chuck Norris' slinky goes UP the stairs." }

This provides us with all we need.

In Postman, We create a new tab (the little + icon) and fill in the following info:

By default, the HTTP Request type is GET. You can see from the dropdown we get a bunch of other options such as POST/PATCH/DELETE etc. Whilst we may not need any of those for this API - the ability to change our request type is crucial for interacting with other APIs that require them.

Anyway, over to the fun! Click Send and you should now see a response with your very own joke! Click Send again, a new joke. Rinse and repeat!

Easy right!

Now, let us use the skills we just learnt to try something else.

Custom Jokes

On the same page, I linked above, there is another example of using the API to get the different categories that are available as well as a way to get jokes within a specific category.

This is a good example of using multiple API endpoints to get what you ultimately one.

In this example, I want to ask for a joke in a specific category. But I don’t know what categories I can pick from.

So the first step is to get those.

Get Joke Categories

GET https://api.chucknorris.io/jokes/categories

So if you now stick that into the top URL box in Postman and hit send - you should get something like me:

We can see from this result we get a list of categories:

[ "animal" , "career" , "celebrity" , "dev" , "explicit" , "fashion" , "food" , "history" , "money" , "movie" , "music" , "political" , "religion" , "science" , "sport" , "travel" ]

So using this information, plus the fact that the docs tell us we can request a joke from a specific category, now we can make a new request with additional info that should return a joke based on the category we asked for. As this is a GET request, any extra data will be in the form of a Query Parameter (key-value pairs in the URL itself)

GET https://api.chucknorris.io/jokes/random?category={category}

However, we can do one better. We can also provide a name query Parameter (weirdly, not documented on the main site but is documented on the sites GitHub page here

So our options are more like

GET https://api.chucknorris.io/jokes/random?category={category}&name={name}

Both parameters are optional so we can omit either or provide both.

Let’s provide both.

Postman makes it simple to add Query Parameters. You can find these under the Params tab below your URL. Here, you can put each parameter Key (category/name) and the value you want.

Name can be whatever, the category must be one from the list we got back in our previous API call.

Let’s see what we get back Awesome. Hopefully, you can see how the general process of discovering what you can do with an API. It can be a lot of trial and error but that is part of the challenge and fun.

I would highly recommend before and after hitting Send that you take a look at the different tabs. The tabs at the top show different parts to your requests, such as Authorisation/Header info (more on that soon) as well as any data you send via GET (Params) or POST (Body)

The tabs above the Response show similar info but this time for the response you get back from the API.

Now let’s move onto our next API where we will take a look POST requests as well as API Authentication.

GitLab API

GitLab is another provider of Git Remote Source Control. This post is not aimed at the tool/platform itself but you can read more about it here. We are going to dig into its REST API which is nicely documented here.

The first place we are going to start is Authentication. This is something we completely overlooked with Chuck Norris facts as it is available without it, but if you are going to spend any time learning about API usage you might as well suck it up and get used to Authenticating to them.

There is plenty of ways to Authenticate with APIs. Such as Username/Password, API Token and OAuth. For simplicity, we are going to go down the API Token route.

This will allow us to generate a Secure Token that effectively authenticates any API requests as our GitLab user.

BE CAREFUL Treat the security API Tokens with seriousness! They are a unique token that represents YOU to a system. If you compromise your token, it is no better than compromising your Username & Password (often worse, if APIs don’t respect any MFA configurations

API Token Authentication

Before we can do anything with the GitLab API, you need to get yourself a token.

Most API tokens are not time-based. Meaning they’ll work way beyond a normal logged-in session.

Tokens are also usually scoped to different levels of permission within an API. If you are using an API that gives you this choice of access, make sure to only give the token the permission you need for your tasks.

When creating your GitLab API, take both of these things into consideration. I will be using a token with full access but it will be deleted before I have posted this so it is limited in its blast radius.

To get your API token for GitLab API Authentication, read this page

Getting API tokens for different APIs differs between each API.

Now, if we take a look at the docs for GitLab, it explains how it expects us to use our token with the API

As you can see, from the examples it gives us, You can provide your token in 3 different ways.

As a Query Parameter (in the request URL)

curl https://gitlab.example.com/api/v4/projects?private_token = < your_access_token >

Via a Private-Token Header

curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects

Via an Authorization Header (common practice)

curl --header "Authorization: Bearer <your_access_token>" https://gitlab.example.com/api/v4/projects

Keep in mind what I’ve said about different APIs having different requirements/expectations. Option 3 is by far the most common way of providing tokens but it isn’t the same for all APIs.

For this post, I am going to go with option 3 - Providing my token as an Authorization header. Don’t worry - Postman makes this easy too.

To use our Token, let’s first find something to try out within the API.

Getting Busy with the API

For our next steps, we are going to be looking at GitLab API Resources

This is a common way of documenting and splitting up API functionality in a predictable and manageable way.

Read through the page and see what I mean. Different GitLab features are covered by different Resources and each Resource has its own endpoints and different features.

For this post we are going to pick a couple of resources to play with, we will determine this by setting ourselves a couple of things to achieve.

This will be:

List GitLab Projects

Get Avatar Information for our user

Create a Project

Delete a Project

List GitLab Projects

So easy peasy now. This will be very similar to our Chuck Norris jokes request.

GET https://gitlab.com/api/v4/projects

Update the URL you want to access to match the above.

Then, to provide our Token, we will select the Authorization tab in Postman then select Bearer Token from the drop-down list.

You’ll see the UI updates to allow you to provide a token. Paste your token here.

Preview Request If you want to see the actual Headers sent, you can click Preview Request , This will update the Headers tab with Temporary Headers. It is here you’ll see the actual result of the Authorization you’ve set.

Now if you click Send you should get a massive list of results - This is all the Public GitLab projects!

Whoop whoop! Easy right!? Again, play with the different tabs to see what is sent/received by Postman.

Extra Credit Take a look at the docs for this Resource, it shows you how you can provide various query parameters to get different output. Such as sort , membership , owned or archived .

Ready for the next one - The steps are going to get less verbose as we are just rinsing and repeating.

Get Avatar Information for our user

GET https://gitlab.com/api/v4/avatar?email=<email>

Same as before. Except we change the endpoint from /projects to /avatar and we’ll provide a Query Parameter for our email.

Hit Send and look at what we get.

Our response includes an avatar_url result with a URL - if you try to access that URL in your browser, you’ll see it provides your user image.

Notice we didn’t have to do anything extra with Authorization. This is because we did it earlier and our Postman session has saved it. You can see why Postman is great!

Create a Project

Creating a project is just another endpoint. The slight difference here is it is now a POST type instead of GET . This tells me that the API endpoint will allow us to send data with our request.

Sending by POST is easy. Change from GET to POST using the dropdown next to our URL.

Reading the Docs for this API endpoint, the attributes we send will be sent via POST data (instead of Query Parameters).

We can supply this info via the Body tab under our URL.

See below for a final state before we hit send:

Content-Type Header This time, take a look at Headers again to see that we now have a new Header called Content-Type with a value of application/json. This was set for us by Postman when we change the Body type to JSON (see the dropdown)

Ready to Hit Send? Go for it. We now get back a response with all the info about our new Project. You can confirm this worked by viewing your GitLab projects within your profile.

Beautiful. Looks like our API call really did do what we asked it to.

Now, to wrap this all up - let’s delete it again. (Unless you don’t want to!)

Delete a Project

Annnddd once more.

This time, change your request type from POST to DELETE . We are going to target:

DELETE https://gitlab.com/api/v4/projects/:id

This time we have something slightly different. Instead of sending POST data via Body or Query Parameters within the URL, we are going to provide the ID of our Project within the URL itself. This is because the Delete API is based on a specific Endpoint including the Project ID.

This pattern is very common - Accessing lists/general information is usually held within a specific path. But if you want to access or adjust (incl. delete in this case) we change the URL to target a specific resource.

In the case of GitLab’s API, it is the HTTP request type that is changing the functionality of the API - This is a good example of how different HTTP Request Types are used to perform different actions.

Anyway, on with the deletion!

We will use the output of the previous POST request which returned the new Project ID to make our new request (similar to how we got categories for Chuck Norris then got a specific Joke based on that category)

So, grab the ID, update the URL and make sure you’re making a DELETE request then hit Send once more.

Now we don’t expect much back this time as we are deleting the resource. Our result in Postman shows we got a message and a response code of 202 stating the request was successful.

Validate this by checking your GitLab projects and notice you’re now missing one :)

Wrapping Up

And we’re done!

There is a lot more to using APIs such as Authentication methods, understanding when to use different API versions and more. Check useful links to find out more, but hopefully, this has provided you with a run-through of the key components to a) What an API is, b) What is a REST API and c) The general rules to interact with them.

I generally apply the same steps and logic to any API I use and it makes understanding and playing with APIs easy when you follow the basics first.

Hopefully, this has helped, I’d be keen to hear what people think and if I’ve missed anything major. Let me know through the usual channels!

Thanks

Neil

Useful Links