Invoke-RestMethod is a powerful cmdlet in Windows PowerShell that allows users to interact with RESTful web services. It is commonly used to send HTTP and HTTPS requests to web APIs and handle the responses. This cmdlet simplifies the process of consuming REST APIs by providing an easy-to-use interface for sending requests and parsing responses.

Understanding Invoke-RestMethod

Invoke-RestMethod is designed to work with RESTful APIs, which use standard HTTP methods such as GET, POST, PUT, and DELETE. It can handle various data formats, including JSON and XML, making it versatile for different API interactions.

Examples

Example 1: Performing a GET Request

Suppose you want to retrieve data from a public API that provides information about users. You can use Invoke-RestMethod to perform a GET request as follows:

# Define the API endpoint
$apiUrl = "https://jsonplaceholder.typicode.com/users"

# Perform a GET request
$response = Invoke-RestMethod -Uri $apiUrl -Method Get

# Display the response
$response

This script sends a GET request to the specified API URL and stores the response in the $response variable. The data is automatically parsed and displayed as PowerShell objects.

Example 2: Sending a POST Request

To send data to an API, you can use the POST method. Here’s how you can create a new user using a POST request:

# Define the API endpoint
$apiUrl = "https://jsonplaceholder.typicode.com/users"

# Create a hashtable with the user data
$userData = @{
    name = "John Doe"
    username = "johndoe"
    email = "johndoe@example.com"
}

# Convert the hashtable to JSON
$jsonData = $userData | ConvertTo-Json

# Perform a POST request
$response = Invoke-RestMethod -Uri $apiUrl -Method Post -Body $jsonData -ContentType "application/json"

# Display the response
$response

In this example, a new user is created by sending a POST request with JSON data. The ConvertTo-Json cmdlet is used to convert the hashtable to JSON format, which is the expected format for the API.

Example 3: Handling Authentication

Some APIs require authentication. Here’s how you can include a basic authentication header in your request:

# Define the API endpoint
$apiUrl = "https://api.example.com/protected/resource"

# Create the credentials
$username = "yourUsername"
$password = "yourPassword"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("${username}:${password}")))

# Perform a GET request with authentication
$response = Invoke-RestMethod -Uri $apiUrl -Method Get -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

# Display the response
$response

This script demonstrates how to include basic authentication in your request by encoding the username and password in base64 and adding it to the request headers.

Conclusion

Invoke-RestMethod is a versatile cmdlet for interacting with RESTful APIs in Windows PowerShell. By understanding how to use it for different HTTP methods and handling authentication, you can effectively integrate API calls into your scripts and automate various tasks.