How to Use Windows PowerShell ‘Invoke-RestMethod’ for JSON APIs

The Evolution of Web Requests

While the Invoke-WebRequest cmdlet in PowerShell is excellent for downloading files or scraping raw HTML from websites, it is cumbersome when dealing with modern REST APIs.

Most modern APIs (like Jira, GitHub, or Microsoft Graph) return data formatted as JSON (JavaScript Object Notation). If you use Invoke-WebRequest, you capture the raw HTTP response, extract the text payload, and then manually pipe it through ConvertFrom-Json to turn it into usable PowerShell objects.

To eliminate these extra steps and drastically speed up API scripting, PowerShell 3.0 introduced Invoke-RestMethod (often aliased as irm). This cmdlet is designed exclusively for API interaction. It automatically parses JSON and XML payloads, instantly converting them into native PowerShell objects the moment they arrive.

1. The Lightning-Fast GET Request

Let’s query a public API that lists information about countries. We want to find the capital of France.

$response = Invoke-RestMethod -Uri "https://restcountries.com/v3.1/name/france"

Because we used Invoke-RestMethod, the $response variable is not a clunky HTTP text object. It is already a fully formed, queryable PowerShell array. We do not need to convert anything.

We can instantly access the data using dot notation:

Write-Host "The capital is: " $response[0].capital

This allows IT administrators to build incredibly concise scripts that interact with complex cloud services.

2. Interacting with Microsoft Graph API

In the enterprise world, Invoke-RestMethod is most frequently used to interact with Azure and Microsoft 365 via the Graph API.

Suppose you want to pull a list of all active users in your Azure Active Directory. You must provide an authorization token in the HTTP Header.

# 1. Define the Authentication Header
$headers = @{
    "Authorization" = "Bearer eyJ0eXAiOiJKV..."
    "Content-Type"  = "application/json"
}

# 2. Query the Graph API
$users = Invoke-RestMethod -Uri "https://graph.microsoft.com/v1.0/users" -Headers $headers -Method GET

# 3. Output the perfectly parsed data
$users.value | Select-Object displayName, userPrincipalName

The cmdlet handles the massive, paginated JSON payload silently in the background, allowing you to pipe the results directly into standard PowerShell formatting cmdlets like Select-Object.

3. Sending Data (POST Requests)

If you want to create a new user, or send an alert into a Slack channel, you must push data to the API using a POST method.

Invoke-RestMethod requires you to format your data as a PowerShell Hashtable, convert it to JSON, and define the Body parameter.

To post a message to a Slack Webhook:

$slackUrl = "https://hooks.slack.com/services/T000/B000/XXXX"

# 1. Create the data payload
$message = @{
    text = "The weekly database backup has completed."
}

# 2. Convert to JSON
$jsonPayload = $message | ConvertTo-Json

# 3. Fire the POST request
Invoke-RestMethod -Uri $slackUrl -Method POST -Body $jsonPayload -ContentType "application/json"

4. Handling API Pagination

Many APIs will not return 10,000 users in a single request. They will return 100 users, and include an @odata.nextLink URL at the very bottom of the JSON payload, telling your script where to go to get the next batch.

Because Invoke-RestMethod automatically converts the JSON, handling pagination in a while loop is incredibly easy:

$url = "https://graph.microsoft.com/v1.0/users"
$allUsers = @()

while ($url) {
    $response = Invoke-RestMethod -Uri $url -Headers $headers -Method GET
    $allUsers += $response.value
    
    # Check if a "Next" link exists
    $url = $response.'@odata.nextLink' 
}

Conclusion

For modern cloud administration, Invoke-RestMethod is the most important cmdlet in the PowerShell ecosystem. By abstracting away the complexities of HTTP response parsing and automatic JSON deserialization, it allows engineers to treat global web APIs as if they were local Windows modules.