Introduction to making REST API calls using PowerShell

0

Since first releasing my post on PowerShell REST API authentication back in Jan 2018 it has become one of the my most popular posts on virtuallysober.com. But that covers authentication, what if you just need to know how to call a REST API using PowerShell?

In this post we are going to use a free world time REST API to show you how to call an API and return useful data, with a little bonus example of parsing a string to get a valid PowerShell datetime object.

First thing we need is a URI (uniform resource identifier) which is basically the URL/endpoint you want to query. I’m going to assign it to a variable for future use (a good best practice, read more on my top 10 tips and tricks here). To get started copy and paste the below into PowerShell:

$WorldTimeZonesURI = "http://worldtimeapi.org/api/timezone/" 

Now we are going to use Invoke-RestMethod function to query the API, and we are going to assign to returned data to a variable:

$WorldTimeZones = Invoke-RestMethod -Uri $WorldTimeZonesURI -Method GET 

The Method GET tells the API we are requesting data, by default Invoke-RestMethod is always a GET so technically we could remove this but I’ll keep it in so you can see the constituent parts. The REST API manual/swagger interface will usually tell you what method to use. To read more on methods click here.

You can now see the data returned by either typing the assigned variable, or here I’m going to output to results to a grid view:

$WorldTimeZones | Out-GridView

If you see a list of time zones then congratulations! You’ve successfully queried your first REST API via PowerShell.

With that simple example out of the way, let’s try a slightly more complicated API call. This time we are going to specify the time zone and return the time. Feel free to change the timezone to any of those returned above. Let’s build and query a new URI containing the timezone name:

$TimeZone = "America/New_York" 
$TimeZoneURI = "http://worldtimeapi.org/api/timezone/" + $TimeZone
$TimeZoneInfo = Invoke-RestMethod -Uri $TimeZoneURI -Method GET
$TimeZoneInfo

You’ll see lots of data returned on the variable, but we want the date time for the zone in a datetime format in PowerShell (so we can work with it). To get that let’s pull the datetime in a string:

$TimeString = $TimeZoneInfo.datetime

Now let’s split it to return everything before the period (as everything after isn’t needed):

$TimeString = $TimeString.split('.')[0] 

With the string correctly formatted, we can convert it to a PowerShell datetime object using:

$Time = ([datetime]::ParseExact($TimeString,”yyyy-MM-ddTHH:mm:ss”,$null))

For more info on PowerShell date time formats use this resource here (one of my regulars). Come to think of it, I should write a post on this topic alone as I’m often using ParseExact to get datetime strings into a useable format. To see the fruit of our work run:

Write-Host "TimeZone:$TimeZone Time:$Time"

You’ve now made 2 successful REST API calls using PowerShell! What will you do with this new found power next? The world is your oyster.

I hope you found this useful. Happy scripting,

Joshua