Invoke-RestMethod: PowerShell’s API Scalpel

Dissecting the REST of the API

---

Homework Discussion

Last Week’s Assignment:

1. Use Get-Command Invoke-WebRequest -Syntax to list every parameter available in your version of PowerShell. Compare your results to the version comparison table.

2. Run Get-Module Microsoft.PowerShell.Utility and note the version number.

3. Write a script that uses Invoke-WebRequest to download three images from a free API (for example, https://picsum.photos/200/300) and save them to disk.

4. Write a script that uses curl.exe to do the same.

5. Which approach do you prefer and why?

• Did you encounter any issues or errors?

• Did any parameters surprise you, or were there options you didn’t expect?

• How did the experience of scripting with PowerShell compare to using curl?

• What did you learn about module versions and compatibility?

• Which method felt more maintainable for future automation?

---

Invocation Infiltration Information

Modern automation is all about talking to APIs. Today’s cloud infrastructure and applications rely heavily on REST services. Invoke-RestMethod was introduced in PowerShell 3.0 (2012), marking a major leap for web automation in Windows scripting. Before its debut, PowerShell users relied on Invoke-WebRequest or .NET’s System.Net.WebClient for HTTP calls, often reading raw responses and writing custom parsers for JSON or XML.

Invoke-WebRequest is the Swiss army knife, while Invoke-RestMethod is a scalpel specifically designed to handle JSON, XML, and other web data formats natively.

With Invoke-RestMethod, PowerShell gained native support for RESTful APIs, automatic parsing of JSON/XML, and a more intuitive experience for scripting. Over the years, the cmdlet has evolved:

• PowerShell 3.0: Initial release, basic REST and JSON support.

• PowerShell 5.0: Improved error handling, support for custom HTTP methods, and better authentication options.

• PowerShell 7+: Cross-platform compatibility, enhanced performance, and support for new web standards.

---

Invoke-RestMethod Parameters Cheat Sheet

Below are the most common parameters for Invoke-RestMethod and a brief summary of their use:

\(\begin{array}{|l|l|}\hline\textbf{Parameter} & \textbf{Summary} \\\hline\text{Uri} & \text{Target URL or endpoint for the request} \\\hline\text{Method} & \text{HTTP method (GET, POST, PUT, etc.)} \\\hline\text{Headers} & \text{Hashtable of custom headers to send} \\\hline\text{Body} & \text{Data sent in the request body (JSON/XML)} \\\hline\text{ContentType} & \text{Media type of the request body (e.g., JSON)} \\\hline\text{Credential} & \text{Credentials for authentication} \\\hline\text{TimeoutSec} & \text{Max time (seconds) to wait for response} \\\hline\text{UserAgent} & \text{Custom user agent string for the request} \\\hline\end{array}\)

For a full list and details, run:

Get-Command Invoke-RestMethod -Syntax

---

Core Syntax Examples

Invoke-WebRequest and Invoke-RestMethod have identical parameters but Invoke-RestMethod automatically parses the response body into PowerShell objects when dealing with JSON or XML content types. This makes it easier to work with api responses directly instead of using ConvertTo-Json or ConvertTo-Xml.

# GET request: Fetching a random joke
$joke = Invoke-RestMethod -Uri "https://official-joke-api.appspot.com/random_joke"
$joke.setup
$joke.punchline

# POST request: Sending data to an API
$body = @{
    name = "JSON is awesome"
    score = 100
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://postman-echo.com/post" -Method POST -Body $body -ContentType "application/json"

#Use dot notation to view the properties
$response.data
$response.headers

You can see that the only conversion needed is for the body when sending data. The response is automatically converted to a PowerShell object.

---

More Examples:

Let’s look as some practical examples of using Invoke-RestMethod, and how the output is difference from Invoke-WebRequest.

• Fetching GitHub Issues:

## INVOKE-RESTMETHOD EXAMPLE ##

# Set the uri of the Powershell repo issues
  $uri = "https://api.github.com/repos/PowerShell/PowerShell/issues"

# Fetch the issues list
  $issuesRest = Invoke-RestMethod -Uri $uri

# Display the first three issues
  $issuesRest | Select-Object -First 3 | Format-Table title, state

## INVOKE-WEBREQUEST EXAMPLE ##

# Same URI, but using Invoke-WebRequest
  $issuesWeb = Invoke-WebRequest -Uri $uri

# To display the first three issues, we need to parse the JSON to convert it to a PowerShell object
  $issuesWeb = $issuesWeb.Content | ConvertFrom-Json
  $issuesWeb | Select-Object -First 3 | Format-Table title, state

Note that with Invoke-RestMethod, the response is already a PowerShell object, while with Invoke-WebRequest, we have to manually parse the JSON content. (However, Invoke-WebRequest provides more detailed HTTP response information, such as headers and status codes.)

• Posting to Teams/Slack:

## INVOKE-RESTMETHOD EXAMPLE ##

# Set the webhook URL (replace with your actual webhook URL)
$uri = "https://slack.com/api/api.test"

#set the body
$body = @{ text = "JSON rocks!" } | ConvertTo-Json

# Post the message
$response = Invoke-RestMethod -Uri $uri -Method POST -Body $body -ContentType "application/json; charset=utf-8"

# INVOKE-WEBREQUEST EXAMPLE ##

# Same URI and body, but using Invoke-WebRequest
$responseWeb = Invoke-WebRequest -Uri $uri -Method POST -Body $body -ContentType "application/json; charset=utf-8"

In the response to the POST request, Invoke-RestMethod will return a parsed object, containing a key called “ok” with a boolean value indicating success or failure. In contrast, Invoke-WebRequest returns a more complex object that includes the raw HTTP response, headers, and status code, requiring additional parsing to extract the relevant information. In most REST scenarios, this extra information is discarded, making Invoke-RestMethod the smarter choice for performance and memory usage.

• Downloading a file

## INVOKE-RESTMETHOD EXAMPLE ##

#Set the uri of the file
$uri = "https://www.fileexamples.com/api/download?file=sample_report.pdf&type=application/pdf"

# Invoke the web request to download the file
Invoke-RestMethod -Uri $uri -OutFile "file-sample_150kB.pdf"

## INVOKE-WEBREQUEST EXAMPLE ##

# Same URI, but using Invoke-WebRequest
Invoke-WebRequest -Uri $uri -OutFile "file-sample_150kB.pdf"

In this case, downloading a file is identical between the two cmdlets, as neither needs to parse the response body.

---

Working Exercise

Write a script that:

• Fetches the latest three public repositories from GitHub’s API for a user of your choice

• Displays the repository name and description in a table

---

Homework

Write a PowerShell script that:

• Uses Invoke-RestMethod to fetch a random joke from Chuck Norris Jokes

• Prints the joke and its category to the console

• Uses Invoke-WebRequest to download a small image (any public image URL)

• Prints the file size of the downloaded image

Extra Credit: Try using both cmdlets in a single script with comments, and open the picture file from inside the script.

---

Final Thought

Invoke-RestMethod and Invoke-WebRequest are powerful tools for interacting with web services and APIs. Choosing the right one depends on your specific needs, but for most RESTful API interactions, Invoke-RestMethod is the more efficient and straightforward choice. Now that the fundamentals are covered, you can explore more advanced scenarios like authentication, error handling, and working with different data formats. Next week we’ll dive into Postman, a popular tool for testing and documenting APIs.