TL;DR: REST APIs let different web services exchange data in a predictable way, and PowerShell makes them practical for sysadmins by using Invoke-RestMethod to send requests, parse JSON responses, and automate repetitive IT tasks. The post explains REST API basics like URIs, endpoints, query strings, headers, bodies, and methods, then shows how to use PowerShell to query data, send body parameters, handle authentication, and work with PDQ Connect’s API to query devices, packages, and groups or deploy packages programmatically.
REST APIs let applications exchange data over the internet using predictable requests and responses. In PowerShell, sysadmins can use Invoke-RestMethod to call REST API endpoints, retrieve JSON data, authenticate requests, and automate repetitive IT tasks across different systems.
What are the main REST API principles?
A Representational State Transfer (REST) API is a type of technology or architecture that allows different web applications to talk to each other and exchange data in a predictable manner. Unlike regular APIs, REST APIs follow a fixed set of rules so you know what to expect and can use them easily across different systems and platforms.
For example, say you need to interact with 10 different web services when setting up a user device. REST APIs allow you to do that programmatically and more efficiently — thanks to the following REST API principles.
1. REST APIs provide a uniform interface
All REST APIs follow a set of standard rules that make them universally applicable. You can easily use commands like Invoke-RestMethod to program and execute tasks across different apps, systems, and platforms.
2. REST APIs are stateless
With REST APIs, each API request is standalone and must contain all the information necessary for the programmed task. Because there’s no need to manage state or session information, REST APIs are more flexible and easier to interact with, making it easier for sysadmins to set up automated workflows.
3. REST APIs have native support for JSON data
Most modern REST APIs return data in JSON format, making it easier to handle with PowerShell (more on that later).
What are the key components of a REST API?
To understand how REST APIs work, you need to know what the key components of a REST API are. Here’s a breakdown.
1. Uniform resource identifier
A uniform resource identifier (URI) is the address of the resource(s) that you want to access or interact with — and appears most commonly as a URL. REST APIs typically have a base URI and an endpoint at the end, which is sometimes followed by a query string.
2. Endpoints
An endpoint is the specific path in a REST API that points to the resource or service you want to access. In the following URI example, the endpoint is /users.
https://jsonplaceholder.typicode.com/users3. Query string
A query string is sometimes added to the URI after the endpoint to set query parameters, specifying what you want to access and filtering out what you don’t. In the REST API example below, the query string is ?id=10&username=Moriah.Stanton. This query parameter returns users with the following ID and username.
https://jsonplaceholder.typicode.com/users/?id=10&username=Moriah.StantonAlways check your API documentation to confirm the parameters you can query. And remember that query strings are case sensitive.
4. Headers
REST API headers are used to control and add additional information about the request. Most of the time, this is where you set up your authorization to handle credentials for authentication.
5. Body
A request body contains data sent to the API, usually when creating, updating, or modifying a resource. In REST APIs, body is often used in addition to or instead of a query string in a URI. And unlike the query string, the body doesn’t change how the URI appears. Body parameters are often used when there’s a change to a resource.
6. Method
A method is the HTTP verb that tells the REST API what action to perform, such as GET, POST, PUT, PATCH, or DELETE. (It’s like you’re training a really smart golden retriever.) For the Invoke-RestMethod, the default method is GET and, just like in PowerShell, is used to retrieve information.
How do you use a REST API with PowerShell?
You can use PowerShell with REST APIs by sending HTTP requests through Invoke-RestMethod. This lets sysadmins retrieve data, send updates, authenticate to web services, and automate IT workflows from the command line.
Which version of PowerShell should you use with REST APIs
Windows PowerShell and PowerShell 7 can both call REST APIs with Invoke-RestMethod. PowerShell 7 is usually the better choice for newer scripts because it includes improved web request behavior and expanded authentication options.
We’ll walk through some common REST API examples that show you how to use REST APIs in PowerShell. The test API in these examples is jsonplaceholder.typicode.com and the default method is GET.
How do you call a REST API with Invoke-RestMethod?
When it comes to REST APIs, using Invoke-RestMethod allows you to interact with APIs and show the results as objects. Using Invoke-RestMethod automatically parses the JSON or XML returned by the API, so you don’t have to do it yourself. (The ability to do more with less is a highly marketable skill in IT.)
If you’re new-ish to REST APIs, the Invoke-RestMethod is the way to go. It’s easy to start with, yet flexible and allows you to use advanced features, like the pipeline. Here’s an example of a GET client request that returns a list of users. If you want data on individual users, you can just add a query string at the end to specific your parameters (see the next example).
$baseUrl = 'http://jsonplaceholder.typicode.com/'
$endpoint = 'users'
$url = $baseUrl + $endpoint
Invoke-RestMethod -Uri $url How to use REST API in PowerShell with a query string
A query string always starts with a ? and an evaluation of property > value. And it’s the same when using REST APIs in PowerShell. You can also add subsequent queries and connect them with an &. In this example, ?id=1&id=2 is the query string. This query parameter returns users that have an ID of 1 or 2.
$baseUrl = 'http://jsonplaceholder.typicode.com/'
$endpoint = 'users'
# query for users with an id of 1 and 2
$queryString = '?id=1&id=2'
# Put it all together to get a URL
$url = $baseUrl + $endpoint + $queryString
$response = Invoke-RestMethod -Uri $url -Method Get
$response How to use REST API in PowerShell with a body
You can use bodies when sending something to the API. You can create a body by creating a hashtable and converting it to JSON. In the following example, we’re using REST APIs in PowerShell to create a new post.
# Build the URL
$base = 'http://jsonplaceholder.typicode.com/'
$endpoint = 'posts'
$url = $base + $endpoint
# Build the body as a PowerShell object
$body = @{
title = 'Why did the programmer bring a ladder to work?'
body = 'Because he wanted to reach new heights in cloud computing. ☁️'
userId = 10
} | ConvertTo-Json
# Build and send the request
Invoke-RestMethod -Uri $url -Method Post -Body $body -ContentType 'application/json' How to use REST API in PowerShell for basic authentication
When using APIs in a work environment, they typically require authentication. With REST APIs, basic authentication is common. In this example — which works in both Windows PowerShell and PowerShell 7 — we use Get-Credential to grab the username and password. (By the way, always avoid putting your passwords into plaintext. And for the love of IT, never write them on Post-its.)
PowerShell 7 comes with big improvements to the Invoke-RestMethod. An additional Authentication parameter offers built-in support for more authentication options, including Basic, Bearer, OAuth, or None.
When setting up authentication, we recommend checking your API documentation to see what they’re looking for.
# Build the URL
$baseUrl = ‘http://jsonplaceholder.typicode.com/’
$endpoint = ‘posts’
$url = $baseUrl + $endpoint
# Get credentials
$credential = Get-Credential
# Create a base64 string for the Authorization header using creds
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes((“{0}:{1}” -f $credential.UserName, $credential.GetNetworkCredential().Password)))
# Build the headers
$headers = @{
Authorization = “Basic $base64AuthInfo”
}
# Send the request
$response = Invoke-RestMethod -Uri $url -Headers $headers -Method Get
# Output the response
$response How to use PDQ Connect’s REST API
You can use PDQ Connect’s API with PowerShell to query devices, list packages, retrieve groups, and deploy packages. This lets sysadmins connect PDQ Connect to scripts, ticketing systems, and other IT workflows.
In the following section, we’ll look at how to use PowerShell with Connect’s API to:
Query devices
Query packages
Query groups
Deploy packages
For those who already have Connect installed, you can follow along with the API documentation here or check out our Help Center article on Connect's API for more details.
Create the API key in Connect
To get started, you first need to create an API key in Connect.
Click Settings > API Keys > Create API Key.
Give it a name to help you identify the API key.
Store your API in a safe place for future reference. (And no, a Post-it under your keyboard is not what we’d call a safe place.)
Authenticate with your API key
After creating your API key in PDQ Connect, the next thing you want to tackle is authentication. Here’s what the code looks like.
$ConnectAPIbaseURL = "https://app.pdq.com/v1/api"
$secureAPIToken = Read-Host -AsSecureString -Prompt "Enter Connect API key"
$tokenPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToGlobalAllocUnicode($secureAPIToken)
$plainAPIToken = [System.Runtime.InteropServices.Marshal]::PtrToStringUni($tokenPtr)
# clean up
[System.Runtime.InteropServices.Marshal]::ZeroFreeGlobalAllocUnicode($tokenPtr)
# Now we can use $plainAPIToken in a call to an API as a bearer token
$headers = @{'authorization' = "Bearer $plainAPIToken"} This code will prompt you for your API key as a secure string before converting it into plain text and inserting it into the $headers variable. Voilà! You now have a $headers and a $connectApiBaseUrl variable to use in future requests.
Query devices using PDQ Connect’s API
You can also query devices using the endpoint /devices using Connect's API. The information to look for is stored in the data property of the query results.
# Grab the device data
$devices = (Invoke-RestMethod -header $headers -uri "$connectApiBaseUrl/devices").Data
# Display all the properties of the devices
$devices | Format-List *
$devices = (Invoke-RestMethod -header $headers -uri "$connectApiBaseUrl/devices").Data
# grab a specific device id
$deviceID = (Invoke-RestMethod -Headers $headers -Uri "$ConnectApiBaseUrl/devices").data | Where-Object hostname -eq 'IROH.whiskeytime.club' | Select-Object -ExpandProperty id
# Grab all properties from your devices
$properties = "disks,drivers,features,networking,processors,updates,software,activeDirectory,activeDirectoryGroups,customFields"
# URL encode the properties
$encodedProperties = [System.Web.HttpUtility]::UrlEncode($properties)
# Grab ALL the data
$devices = (Invoke-RestMethod -header $headers -uri "$connectApiBaseUrl/devices?includes=$encodedproperties").Data Query packages using PDQ Connect’s API
When querying packages, the code below also takes advantage of the page query string, looping through and returning the full set of results.
It’s important to note that the API only returns up to 100 responses. If you have more than 100 packages and want to list them all, you’ll need to submit multiple requests using code like the one below.
# find packages containing a string, like firefox
(Invoke-RestMethod -Headers $headers -Uri "$ConnectApiBaseUrl/packages?filter[name]=~firefox").Data
# return packages containing a package name
$name = "Uninstall Firefox (per User)"
$encodedQuery = [System.Web.HttpUtility]::UrlEncode($name)
$packageID = (Invoke-RestMethod -Headers $headers -Uri "$ConnectApiBaseUrl/packages?filter[name]=$encodedQuery").Data.ID
# Loop through and return all packages
$page = 1 # Initialize page number
$hasMoreResults = $true
$packages = @()
while ($hasMoreResults) {
# Call the API with the current page number
$response = Invoke-RestMethod -Uri "$ConnectApiBaseUrl/packages?page=$page" -Headers $headers
# If the response's data property is empty, no more results
if (!$response.Data) {
$hasMoreResults = $false # Stop looping
}
else {
# Process the results
$response.Data | ForEach-Object {
$Packages += $_
}
# Move to the next page
$page++
}
}
Write-Output $Packages Query groups using PDQ Connect’s API
When querying groups, the groupID is helpful to have on hand for future deployments. Since the API returns only up to 100 responses each time, you can use the code in the previous section to loop through your groups if necessary and get the full results.
$groups = (Invoke-RestMethod -Headers $headers -Uri "$ConnectApiBaseUrl/groups").data
$groupID = $groups | Where-Object Name -eq "Missing Office" | Select -ExpandProperty id Deploy packages using PDQ Connect’s API
For package deployments, the code below takes advantage of the $packageID and $deviceID, which we’d set earlier when querying packages and devices.
$Uri = "$ConnectApiBaseUrl/deployments?package=$packageID&targets=$deviceID"
Invoke-RestMethod -Headers $headers -Method Post -Uri $Uri And that, my friends, is how you can use PowerShell, REST APIs, and a handy device management tool like PDQ Connect to carry out day-to-day tasks a little more efficiently. Now, you can go forth and automate at will.
For sysadmins managing a ton of different devices and daily tasks, using REST APIs is a pretty neat way to bring order to the chaos. You can try PDQ Connect for free to see how you can better manage devices anywhere from the cloud.
