PowerShell REST APIs and Web Requests Cheat Sheet

$ApiUri = 'https://api.example.com/v1/widgets'
$Items = Invoke-RestMethod -Uri $ApiUri -Method Get
$Items | Write-Output | Select-Object -Property id, name

$Response = Invoke-WebRequest -Uri $ApiUri -Method Head
[pscustomobject]@{
    Status      = $Response.StatusCode
    ContentType = $Response.Headers['Content-Type']
}

$BaseUri = 'https://api.example.com/v1/widgets'
$Query = @{
    q    = 'blue widget'
    page = 2
}
$Matches = Invoke-RestMethod -Uri $BaseUri -Method Get -Body $Query

$Payload = @{
    name = 'blue widget'
    tags = @('new', 'fragile')
} | ConvertTo-Json -Depth 10
$Created = Invoke-RestMethod -Uri $BaseUri -Method Post `
    -Body $Payload -ContentType 'application/json; charset=utf-8'

$Token = Read-Host 'API token' -AsSecureString
$Headers = @{
    Accept = 'application/json'
}
try {
    Invoke-RestMethod -Uri 'https://api.example.com/v1/profile' `
        -Authentication Bearer -Token $Token -Headers $Headers
}
finally {
    $Token.Dispose()
    Remove-Variable -Name Token
}

Note: For unattended automation, replace the prompt with an approved secret provider that returns a SecureString.

$BaseUri = 'https://api.example.com'
Invoke-WebRequest -Uri "$BaseUri/session" -SessionVariable ApiSession | Out-Null
try {
    Invoke-RestMethod -Uri "$BaseUri/v1/profile" -WebSession $ApiSession
}
finally {
    Remove-Variable -Name ApiSession -ErrorAction SilentlyContinue
}

$Thumbprint = 'REPLACE_WITH_REVIEWED_THUMBPRINT'
$Certificate = Get-Item -LiteralPath "Cert:\CurrentUser\My\$Thumbprint"
Invoke-RestMethod -Uri 'https://api.example.com/v1/secure' `
    -Certificate $Certificate -SslProtocol Tls12

$Origin = [uri]'https://api.example.com/'
$Next = [uri]'https://api.example.com/v1/widgets?limit=100'
$Seen = [System.Collections.Generic.HashSet[string]]::new()
for ($Page = 1; $Next -and $Page -le 20; $Page++) {
    if ($Next.Scheme -ne $Origin.Scheme -or $Next.Authority -ne $Origin.Authority) {
        throw "Rejected pagination target: $Next"
    }
    if (-not $Seen.Add($Next.AbsoluteUri)) { throw 'Pagination cycle detected' }
    $Result = Invoke-RestMethod -Uri $Next -Method Get
    $Result.items
    $Next = if ($Result.next) { [uri]::new($Origin, [string]$Result.next) } else { $null }
}
if ($Next) { throw 'Pagination exceeded 20 pages' }

$Uri = 'https://api.example.com/v1/health'
$RequestJob = Start-Job -ScriptBlock {
    Invoke-RestMethod -Uri $using:Uri -Method Get `
        -ConnectionTimeoutSeconds 10 -OperationTimeoutSeconds 30 `
        -MaximumRetryCount 3 -RetryIntervalSec 2
}
try {
    Wait-Job -Job $RequestJob -Timeout 120 | Out-Null
    if ($RequestJob.State -notin @('Completed', 'Failed')) {
        Stop-Job -Job $RequestJob
        throw 'Request exceeded the 120-second workflow deadline'
    }
    Receive-Job -Job $RequestJob -ErrorAction Stop
}
finally {
    Remove-Job -Job $RequestJob -Force -ErrorAction SilentlyContinue
}

$Uri = 'https://example.com/releases/artifact.zip'
$Staging = Join-Path $env:TEMP 'artifact.zip.part'
$Destination = Join-Path $PWD 'artifact.zip'
$ExpectedSha256 = 'REPLACE_WITH_PUBLISHER_SHA256'
Invoke-WebRequest -Uri $Uri -OutFile $Staging
$ActualSha256 = (Get-FileHash -LiteralPath $Staging -Algorithm SHA256).Hash
if ($ActualSha256 -ne $ExpectedSha256) {
    Remove-Item -LiteralPath $Staging -Force
    throw "Artifact digest mismatch: $ActualSha256"
}
Move-Item -LiteralPath $Staging -Destination $Destination

Note: Obtain the expected digest independently from the publisher; do not trust a hash downloaded from the same unverified location.

$Body = Invoke-RestMethod -Uri 'https://api.example.com/v1/widgets/42' `
    -SkipHttpErrorCheck -StatusCodeVariable Status `
    -ResponseHeadersVariable ResponseHeaders
if ($Status -ge 400) {
    $RequestId = $ResponseHeaders['Request-Id']
    throw "API request failed with HTTP $Status; request ID $RequestId"
}
$Body

try {
    Invoke-RestMethod -Uri 'https://api.example.com/v1/widgets/42' -ErrorAction Stop
}
catch {
    $Status = if ($_.Exception.Response) {
        [int]$_.Exception.Response.StatusCode
    } else {
        $null
    }
    Write-Error "Request failed; HTTP status: $Status; category: $($_.CategoryInfo.Category)"
}

$Command = Get-Command Invoke-RestMethod
$Parameters = @{
    Uri    = 'https://api.example.com/v1/health'
    Method = 'Get'
}
if ($Command.Parameters.ContainsKey('StatusCodeVariable')) {
    $Parameters.StatusCodeVariable = 'Status'
}
Invoke-RestMethod @Parameters

Get-Command curl -ErrorAction SilentlyContinue | Select-Object Name, CommandType
curl.exe --fail --output artifact.zip https://example.com/artifact.zip

Note: In Windows PowerShell 5.1, plain curl resolves to Invoke-WebRequest; PowerShell 7 does not define that alias.