Understanding the Invoke-RestMethod PowerShell cmdlet

• Author
• Recent Posts

Adam Bertram

Adam Bertram is a 20-year IT veteran, Microsoft MVP, blogger, and trainer.

Latest posts by Adam Bertram (see all)

• Create a certificate-signed RDP shortcut via Group Policy - Fri, Aug 9 2019
• Monitor web server uptime with a PowerShell script - Tue, Aug 6 2019
• How to build a PowerShell inventory script for Windows Servers - Fri, Aug 2 2019

REST APIs allow developers to interact with various services over HTTP/HTTPS and follow a common methodology of using methods to read and manipulate information. They return information in a standard way, typically through JavaScript Object Notation (JSON). The Invoke-RestMethod cmdlet is built with REST in mind. It allows the user to invoke various methods for web service APIs and easily parse the output.

To explain the Invoke-RestMethod command, let's start with a simple example. Let's say I'm fiending for some information about cats and discover a REST API called Cat Facts. This API returns various facts about our feline friends and is a great API to demonstrate how Invoke-RestMethod works.

All REST APIs have a base URL and one or more endpoints. The base URL for Cat Facts is https://cat-fact.herokuapp.com, and the endpoint we'll be using is /facts. When we combine these, we get the endpoint URI or https://cat-fact.herokuapp.com/facts.

One of the Invoke-RestMethod command's biggest advantages is its native parsing ability. Invoke-RestMethod understands that a URI is REST and will probably return JSON. When the API does return JSON, Invoke-RestMethod will parse the JSON and return useful PowerShell objects. To demonstrate, I'll use the Invoke-RestMethod command's brother, Invoke-WebRequest. The Invoke-WebRequest command performs a similar function by sending HTTP verbs to web services but does not have the parsing ability Invoke-RestMethod does.

If I run Invoke-WebRequest against our Cat Facts API, we have to look at the Content property, which contains a whole lot of unparsed JSON.

Using Invoke WebRequest against a REST API

We could parse this JSON ourselves, but there's no need when using Invoke-RestMethod. This command looks at the output and parses it. Here's the difference:

Using Invoke RestMethod

Notice we didn't have to specify the Content property at all. Invoke-RestMethod natively returns the HTTP content and automatically parses the JSON, allowing us to work with the JSON data via PowerShell objects.

Invoke-RestMethod also has some other useful features when working with REST APIs, such as authentication. Some APIs require you to authenticate via a username/password with basic authentication or perhaps an OAuth token. We can use the Credential parameter to pass a username and password if the API supports basic authentication. Usually, though, you'll find a lot of APIs require an OAuth token. For a great explanation on working with OAuth with PowerShell, check out Stephen Owen's blog post.

The Invoke-RestMethod command allows you to pass OAuth tokens and other information the API needs via HTTP headers using the Headers parameter. Perhaps the REST API is set up to accept OAuth tokens using the command Authorization key. We can pass our OAuth token with Invoke-RestMethod like so:

Invoke-RestMethod -Uri 'https://cat-fact.herokuapp.com/facts' -Headers @{ 'Authentication' = 'Bearer xxxxxxxxxxxxxxxx' }

This command doesn't just retrieve information via APIs using the HTTP GET method sent by default. We can use many different HTTP methods like POST, PATCH, PUT, and UPDATE as well. We simply need to specify the method via the Method parameter and then provide an HTTP body using the Body parameter.

Perhaps we have a REST API that accepts a POST request and expects the body to be in JSON format. We've already saved our JSON payload in a variable called $jsonSample looking something like this:

{
    "SomeElement" : "Foo"
}

We can pass this JSON payload to the Body parameter and optionally use the ContentType parameter to tell the API that the payload is JSON. This step isn't always required, but it is common. Our Invoke-RestMethod API call would then look something like this:

P

$token = 'xxxxxxxxxx'
$params = @{
    Uri         = 'https://cat-fact.herokuapp.com/facts'
    Headers     = @{ 'Authorization' = "Bearer $token" }
    Method      = 'POST'
    Body        = $jsonSample
    ContentType = 'application/json'
}
Invoke-RestMethod @params

The command above will authenticate to the URI endpoint, pass the JSON sample via the HTTP POST method, and tell the API that the content is JSON. If the API returns a response, Invoke-RestMethod will return it to the console already parsed.

The Invoke-RestMethod command is a great way to interact with REST APIs in PowerShell. Although most if not all of its functionality can take place via a combination of Invoke-WebRequest, ConvertTo-Json, and ConvertFrom-Json commands, it's a great all-in-one command that does all the heavy lifting for you.