Last Updated on July 6, 2024 by Arnav Sharma
The Invoke-RestMethod cmdlet in PowerShell is used to send HTTP and HTTPS requests to RESTful web services. It is a versatile cmdlet that can be used to interact with REST APIs, making it possible to send GET, POST, PUT, DELETE, and other types of HTTP requests.
Here’s a detailed explanation of Invoke-RestMethod with examples:
Syntax
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-Uri] <Uri>
[-Body <Object>]
[-Headers <IDictionary>]
[-ContentType <String>]
[-Credential <PSCredential>]
[-Authentication <WebAuthenticationType>]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-TimeoutSec <Int32>]
[<CommonParameters>]
Parameters
- -Method: Specifies the HTTP method to use (GET, POST, PUT, DELETE, etc.). Default is GET.
- -Uri: Specifies the URI of the RESTful web service.
- -Body: Specifies the data to send to the web service. This is often used with POST and PUT requests.
- -Headers: Specifies custom headers for the web request as a hashtable.
- -ContentType: Specifies the content type of the request body, such as
application/json. - -Credential: Specifies the user credentials to use for the web service.
- -Authentication: Specifies the authentication type to use.
- -CertificateThumbprint: Specifies the thumbprint of a certificate to use for the request.
- -Certificate: Specifies a certificate to use for the request.
- -TimeoutSec: Specifies the timeout in seconds for the web request.
Examples:
Example 1: GET Request
This example retrieves data from a REST API using a GET request.
$uri = "https://jsonplaceholder.typicode.com/posts/1"
$response = Invoke-RestMethod -Uri $uri -Method GET
$response
Example 2: POST Request with JSON Body
This example sends data to a REST API using a POST request.
$uri = "https://jsonplaceholder.typicode.com/posts"
$body = @{
title = "foo"
body = "bar"
userId = 1
} | ConvertTo-Json
$response = Invoke-RestMethod -Uri $uri -Method POST -Body $body -ContentType "application/json"
$response
Example 3: POST Request with Headers
This example sends data to a REST API using a POST request and includes custom headers.
$uri = "https://jsonplaceholder.typicode.com/posts"
$body = @{
title = "foo"
body = "bar"
userId = 1
} | ConvertTo-Json
$headers = @{
Authorization = "Bearer YOUR_ACCESS_TOKEN"
"Custom-Header" = "HeaderValue"
}
$response = Invoke-RestMethod -Uri $uri -Method POST -Body $body -ContentType "application/json" -Headers $headers
$response
Example 4: PUT Request
This example updates data on a REST API using a PUT request.
$uri = "https://jsonplaceholder.typicode.com/posts/1"
$body = @{
id = 1
title = "foo"
body = "bar"
userId = 1
} | ConvertTo-Json
$response = Invoke-RestMethod -Uri $uri -Method PUT -Body $body -ContentType "application/json"
$response
Example 5: DELETE Request
This example deletes data from a REST API using a DELETE request.
$uri = "https://jsonplaceholder.typicode.com/posts/1"
$response = Invoke-RestMethod -Uri $uri -Method DELETE
$response
Explanation of Responses
Invoke-RestMethod automatically converts JSON and XML responses into PowerShell objects, making it easy to work with the data. For example, if the response is in JSON format, PowerShell will convert it into a PSCustomObject that you can access using dot notation.
Error Handling
To handle errors, you can use try-catch blocks. For example:
try {
$uri = "https://jsonplaceholder.typicode.com/posts/1"
$response = Invoke-RestMethod -Uri $uri -Method GET
$response
}
catch {
Write-Error $_.Exception.Message
}
FAQ:
Q: What is the Invoke-RestMethod cmdlet used for in PowerShell?
A: The Invoke-RestMethod cmdlet in PowerShell is used to send HTTP and HTTPS requests to REST endpoints and handle the response.
Q: How do you specify the URI when using Invoke-RestMethod in PowerShell?
A: You specify the URI using the -Uri parameter in the request method. Invoke-RestMethod command.
Q: What is the purpose of the -Method parameter in Invoke-RestMethod?
A: The -Method parameter in Invoke-RestMethod specifies the HTTP method to use for the request, such as GET, POST, PUT, or DELETE.
Q: How can you include the body of the request in an Invoke-RestMethod call?
A: You can include the body of the request using the Invoke-RestMethod -Uri parameters in the same command. -Body parameter in the Invoke-RestMethod call.
Q: What should you do if the REST endpoint requires authentication?
A: If the REST endpoint requires authentication, you need to include appropriate authentication parameters, such as using the -Credential parameter.
Q: How can you include query parameters in your Invoke-RestMethod request?
A: You can include query parameters by appending them to the URI or by using the -Query parameter.
Q: How does PowerShell format the response from Invoke-RestMethod?
A: PowerShell formats the response based on the data type returned by the REST endpoint, typically converting it into a richly structured object.
Q: What should you use if you need to share state and data among web requests in PowerShell?
A: You should use the variable to share state and data among web requests in PowerShell.
Q: How do you specify a proxy server for the request in Invoke-RestMethod?
A: You specify a proxy server for the request using the -Proxy parameter in the Invoke-RestMethod command.
Q: What does the -ProxyCredential parameter do in Invoke-RestMethod?
A: The -ProxyCredential parameter specifies the credentials to use for proxy authentication in Invoke-RestMethod.
Q: What is the -PassThru parameter used for in Invoke-RestMethod?
A: The -PassThru parameter is used to save the response body to a variable for further processing.
Q: Can you use Invoke-RestMethod for a secure web request?
A: Yes, you can use Invoke-RestMethod for a secure web request by including the appropriate parameters and ensuring the connection is secure.
Q: How does PowerShell handle the response body from an Invoke-RestMethod call?
A: PowerShell saves the response body and converts it based on the content type of the response.
Q: What happens if you need to use a network proxy server in Invoke-RestMethod?
A: You can use the Invoke-RestMethod -Uri command in Windows PowerShell to create a web API call. -Proxy and -ProxyCredential parameters to specify and authenticate with a network proxy server.
Q: What is the typical timeout for an Invoke-RestMethod call?
A: The typical timeout for an Invoke-RestMethod call is 15 seconds to return or timeout.
Q: How can you specify the content type of the request in Invoke-RestMethod?
A: You can specify the content type of the request using the appropriate parameters in the same command. -ContentType parameter in Invoke-RestMethod.