Automation Course Part 1 – What is a REST API?

This is Part 1 of an 11-part series intended to bootstrap the typical IT technician (with some existing PowerShell skills) to be able to build tools and automation using Microsoft PowerShell and Azure. There’s a lot more to cover to build reliable and scalable tools for production, but we hope this helps you get started!

As an IT technician, you might have heard the term “REST API” being thrown around a lot. But what exactly is it, and how can it benefit you in your work? In this article, we will explore what a REST API is and what types of problems it is useful for, and then dive in to some basic REST request examples using PowerShell.

REST API stands for “Representational State Transfer Application Programming Interface.” This might sound like a mouthful, but essentially, it is a way for different software applications to communicate with each other over the internet. RESTful APIs are built around the HTTP protocol, and they allow applications to send and receive data using standard HTTP methods like GET, POST, PUT, and DELETE.

One of the primary benefits of REST APIs is that they enable developers to create modular, scalable applications. By breaking up a large application into smaller components, each with its own API, developers can more easily update and improve the application over time. Additionally, REST APIs allow for better collaboration between different teams, as each team can work on their own API endpoints without interfering with others.

As an IT technician, you’ll probably primary use REST APIs for extending the functionality of existing platforms, “gluing” together data from different 3rd party platforms, automating interactions between those platforms. Some things GreenLoop uses REST APIs for:

1. Scheduling recurring events (breaks, training, work-from-home time, etc.) for our technicians in ConnectWise Manage
2. Importing and exporting ConnectWise Manage projects
3. Backing up our IT Glue instance to Azure storage automatically
4. Automatically restarting client UniFi environments on a schedule

Now let’s take a look at some sample PowerShell code for interacting with a dummy API endpoint.

For this tutorial, assume we have an API endpoint at https://dummyapi.com/users. We’d use the following code to perform a GET request:

$uri = "https://dummyapi.com/users"
$response = Invoke-RestMethod -Uri $uri -Method Get 
$response

Just as the name implies, a GET request retrieves specific data from the endpoint. This code sends a GET request to the API endpoint and returns the response as a PowerShell object, $response.

Since no specific user is specified, this GET request will return all objects at that endpoint. Individual objects in a REST API are required to have a unique ID. If you know that unique ID, you can use a GET request to get just that single object with all of its key-value pairs:

$uri = "https://dummyapi.com/users/1" #get the user with ID = 1
$response = Invoke-RestMethod -Uri $uri -Method Get
$response

A different type of request, a POST request, is commonly used to send data to the server to create a brand new object. To perform a POST request, we can use the following code:

$uri = "https://dummyapi.com/users"
$body = @{
 name = "John Doe"
 email = "johndoe@example.com"
}
$jsonBody = ConvertTo-Json $body
$response = Invoke-RestMethod -Uri $uri -Method Post -Body $jsonBody -ContentType "application/json"

This code sends a POST request to the API endpoint with a JSON body containing a name and email. The API will create a new user with this data and return the new user’s details in the $response.

Notice how I’ve specified the $body variable as a PowerShell hashtable first, and then used ConvertTo-Json in order to create an actual JSON object. You can also create a JSON object manually, but this pattern is a best practice you should get used to–it makes it much simpler to manipulate the object (for instance, adding, removing, and replacing members).

The last REST verb we’ll cover in this article is PUT. This is typically used when the object already exists, but you want to add additional information to it. Below is a code snippet of a PUT request. Note how I’ve used the object ID (“123”) at the end of the URI to specify which object we want to update. The $body again contains a JSON representation of the attributes we want to update.

$uri = "https://dummyapi.com/users/123"
$body = @{
 email = "newemail@example.com"
}
$jsonBody = ConvertTo-Json $body
$response = Invoke-RestMethod -Uri $uri -Method Put -Body $jsonBody -ContentType "application/json"