Invoke RestMethod - PowerShell

Overview

Invoke-RestMethod allows you to send HTTP requests and retrieve responses from RESTful web services within PowerShell. This versatile command enables interfacing with remote web APIs, retrieving data, and performing various tasks. It is a powerful tool for PowerShell users seeking to integrate with external web applications and services.

Syntax

Invoke-RestMethod [-Uri] <Uri> [-Method] <String> [-Body] <Object> [-Headers] <Hashtable> [-Parameters] <Hashtable> [-ContentType] <String> [-Accept] <String> [-UserAgent] <String> [-WebSession] <WebSession> [-Timeout] <Int32> [-MaxRetry] <Int32> [-UseBasicParsing] [-ErrorAction] <ActionPreference> [-ErrorVariable] <String> [-OutFile] <String> [-OutVariable] <String> [-PassThru]

Options/Flags

-Uri : The URI of the RESTful web service you want to interact with. This is a required parameter.

-Method : The HTTP request method to use, such as ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’, ‘PATCH’, or ‘HEAD’. The default value is ‘GET’.

-Body : The body of the HTTP request as a PowerShell object. This is used for requests requiring a request body, such as ‘POST’ or ‘PUT’. The default value is $null.

-Headers : A hashtable containing the HTTP headers to include in the request. The default value is $null.

-Parameters : A hashtable containing the query parameters to include in the URI. The default value is $null.

-ContentType : The content type of the request body. The default value is ‘application/json’.

-Accept : The content type you expect in the response. The default value is ‘/‘.

-UserAgent : The user agent string to use in the request. The default value is ‘PowerShell’.

-WebSession : A PowerShell web session to use. This allows you to reuse an existing session for improved performance. The default value is $null.

-Timeout : The number of milliseconds to wait for a response before timing out. The default value is 100000 (100 seconds).

-MaxRetry : The maximum number of times to retry a failed request. The default value is 0 (no retries).

-UseBasicParsing : If set, the response will be parsed using a basic parser, ideal for XML or text responses. The default value is $false.

-ErrorAction : The action to perform when an error occurs. The default value is ‘Stop’.

-ErrorVariable : The name of the variable to store the error message in. The default value is $null.

-OutFile : The file path to save the response to. The default value is $null.

-OutVariable : The name of the variable to store the response in. The default value is $null.

-PassThru : If set, the response object will be passed through the pipeline. The default value is $false.

Examples

Simple GET request:

Invoke-RestMethod -Uri "https://example.com/api/users"

POST request with a request body:

$body = @{ Name = "John"; Age = 30 }
Invoke-RestMethod -Uri "https://example.com/api/users" -Method "POST" -Body $body

Retrieving a response as JSON:

$response = Invoke-RestMethod -Uri "https://example.com/api/users" -UseBasicParsing
$users = $response.JsonObject

Saving the response to a file:

Invoke-RestMethod -Uri "https://example.com/api/users" -OutFile "users.json"

Common Issues

  • 404 Not Found: Ensure the URI is correct and accessible.
  • 401 Unauthorized: Verify your credentials or ensure the API requires authentication.
  • Timeout errors: Increase the timeout value using the -Timeout parameter.
  • Parse errors: Use the -UseBasicParsing switch parameter for responses that are not in JSON format.
  • SSL errors: Ensure the server’s SSL certificate is trusted or use the -Insecure parameter to bypass SSL certificate checking (not recommended for production environments).

Integration

Invoke-RestMethod can be combined with other PowerShell commands or tools for more complex tasks:

  • Piping results to other commands:
Invoke-RestMethod -Uri "https://example.com/api/users" | Out-File "users.txt"
  • Using web sessions for improved performance:
$session = New-WebSession
Invoke-RestMethod -Uri "https://example.com/api/users" -WebSession $session
  • Creating scripts to automate API interactions:
Write your own PowerShell scripts to automate repetitive or complex API interactions using Invoke-RestMethod.