Getting Started With REST APIs in PowerShell

The REST API, also known as the RESTful API, is a protocol used to interact with web applications. Although REST calls are typically made through a browser or application, you can also use PowerShell to engage with a REST API.

When using a REST API, you must tell the API the method you want to use. For example, the GET method is used to retrieve data from an application, while the POST method is used to create new data. Other REST methods include PUT, PATCH, and DELETE.

When submitting a request to a REST API, you will need to provide a properly structured request body. The API will then return a response to that request. The structure of the body depends on the specific method being used.

Since this article is intended for beginners, let’s focus on using the GET method to retrieve data from a REST API.

Retrieving Data From REST APIs in PowerShell

I am focusing on the GET method because it doesn’t require creating a hash table, unlike some other methods. Assuming the API doesn’t require authentication, you only need to specify the API’s URI and the method you want to use.

In some ways, however, this is simplifying things a bit. In real-world scenarios, GET requests almost always include parameters that specify the data you want to retrieve from the API.

Related:How To Build ChatGPT-Enabled PowerShell Scripts

As an example, let’s look at an API related to a trivial game located at https://opentdb.com/api.php. I found the API listed on a webpage with various API examples.

To get trivia questions from the API using a GET request, you need to include two values: Amount and Category. These values are typically in the HTTPS request.

Here’s an example of such a request and the results: https://opentdb.com/api.php?amount=1&category=18. When you make this request, the API returns raw data in JSON format, as shown in Figure 1.

REST 1

Figure 1: This browser-based API call returns raw data in JSON format.

In PowerShell, you could enter the URI exactly as it is listed above. However, if you were building a PowerShell-based trivia game, likely you wouldn’t want to make the same URI call every time. Instead, you might store the Amount and Category values in variables to update them as the game progresses. This would require using string manipulation to construct the URI dynamically.

Here is an example of how you could do it in PowerShell:

$Amount=1$Category=18$URI=”https://opentdb.com/api.php?amount=” + $Amount + “&category=” + $Category

You can see these commands and the resulting URI in Figure 2.

REST 2

Figure 2. This is how you form a custom URI.

After forming the URI, you can specify the method to use. You can specify a method directly, but I prefer to store the method in a variable like this:

$Method = “Get”

To query the API, you need only to use PowerShell’s Invoke-RestMethod cmdlet and specify the method and URI:

Invoke-RestMethod -Method $Method -URI $URI

You can see this command in action in Figure 3. Notice that the API returns the results in JSON format.

REST 3

Figure 3. A trivia question has been retrieved from a web app using a REST API.

Normally, that’s all that is required for submitting a GET request to a REST API. In some cases where the API requires authentication, you may need to include the -Credential parameter along with credentials.

Converting Data Into a PowerShell Object

Before concluding this article, let’s look at how to convert the retrieved data into a usable format.

The simplest approach is to map the Invoke-RestMethod cmdlet to a variable. For example, you might use the following command:

$APICall = Invoke-RestMethod -Method $Method -URI $URI

When using this technique, PowerShell automatically converts the received JSON data into Object format, which offers several advantages. To view the data, simply type $APICall.Results. If you need to access specific data fields, you can use the Select-Object cmdlet.

REST 4

Figure 4. The data has been written to a PowerShell object and can be accessed like any other PowerShell data.