Working with APIs

The Report That Automated Itself

I used to spend 2 hours every Monday morning generating a deployment report: log into Azure DevOps, click through 15 project pipelines, copy data to Excel, calculate statistics, email the team. Every. Single. Monday.

One weekend, I discovered Azure DevOps has a REST API:

$org = "mycompany"
$project = "MainApp"
$pat = $env:AZDO_PAT

$headers = @{
    Authorization = "Basic $([Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat")))"
}

$builds = Invoke-RestMethod -Uri "https://dev.azure.com/$org/$project/_apis/build/builds?api-version=7.0" -Headers $headers

$builds.value | Select-Object id, buildNumber, status, result | Export-Csv "builds.csv"

Two hours became 30 seconds. That script still runs every Monday, automatically.

Invoke-RestMethod: Your API Swiss Army Knife

Invoke-RestMethod calls REST APIs and automatically parses responses.

Basic GET Request

# Simple GET
$response = Invoke-RestMethod -Uri "https://api.github.com/users/powershell"

# Access properties
$response.login
$response.name
$response.public_repos

HTTP Methods

# GET (retrieve data)
Invoke-RestMethod -Uri "https://api.example.com/items" -Method Get

# POST (create data)
$body = @{
    name = "New Item"
    value = 100
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://api.example.com/items" -Method Post -Body $body -ContentType "application/json"

# PUT (update data)
Invoke-RestMethod -Uri "https://api.example.com/items/1" -Method Put -Body $body -ContentType "application/json"

# DELETE (remove data)
Invoke-RestMethod -Uri "https://api.example.com/items/1" -Method Delete

Authentication

Bearer Token

$token = "your-api-token"

$headers = @{
    Authorization = "Bearer $token"
}

Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers

Basic Authentication

$username = "user"
$password = "pass"
$base64Auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("${username}:${password}"))

$headers = @{
    Authorization = "Basic $base64Auth"
}

Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers

API Key

$headers = @{
    "X-API-Key" = "your-api-key"
}

Invoke-RestMethod -Uri "https://api.example.com/data" -Headers $headers

Working with JSON

Parsing JSON Responses

# Invoke-RestMethod automatically parses JSON
$repos = Invoke-RestMethod -Uri "https://api.github.com/users/powershell/repos"

# Access array
$repos | Select-Object name, stargazers_count, language

# Filter
$repos | Where-Object {$_.language -eq "PowerShell"} | 
    Select-Object name, stargazers_count

Sending JSON Data

$data = @{
    title = "My Task"
    description = "Task description"
    priority = "High"
    tags = @("urgent", "backend")
}

$json = $data | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://api.example.com/tasks" `
    -Method Post `
    -Body $json `
    -ContentType "application/json"

Nested JSON

$complex = @{
    user = @{
        name = "John Doe"
        email = "[email protected]"
        settings = @{
            theme = "dark"
            notifications = $true
        }
    }
    permissions = @("read", "write")
}

$json = $complex | ConvertTo-Json -Depth 10  # Depth for nested objects

Real-World API Examples

GitHub API Integration

function Get-GitHubRepoInfo {
    param(
        [string]$Owner,
        [string]$Repo
    )
    
    $uri = "https://api.github.com/repos/$Owner/$Repo"
    $repo = Invoke-RestMethod -Uri $uri
    
    [PSCustomObject]@{
        Name = $repo.name
        Description = $repo.description
        Stars = $repo.stargazers_count
        Forks = $repo.forks_count
        Language = $repo.language
        Created = $repo.created_at
        Updated = $repo.updated_at
        URL = $repo.html_url
    }
}

# Usage
Get-GitHubRepoInfo -Owner "PowerShell" -Repo "PowerShell"

Azure DevOps API

$org = "myorg"
$project = "myproject"
$pat = $env:AZDO_PAT  # Personal Access Token

$base64Auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat"))
$headers = @{
    Authorization = "Basic $base64Auth"
}

# Get recent builds
$buildsUri = "https://dev.azure.com/$org/$project/_apis/build/builds?`$top=10&api-version=7.0"
$builds = Invoke-RestMethod -Uri $buildsUri -Headers $headers

$builds.value | Select-Object @{N='Build';E={$_.buildNumber}}, 
                               @{N='Status';E={$_.status}}, 
                               @{N='Result';E={$_.result}}, 
                               @{N='Started';E={$_.startTime}} |
    Format-Table

REST API with Pagination

function Get-AllPages {
    param([string]$Uri)
    
    $allResults = @()
    $nextUri = $Uri
    
    while ($nextUri) {
        $response = Invoke-RestMethod -Uri $nextUri
        $allResults += $response.items
        
        # Check for next page
        $nextUri = $response.nextLink
    }
    
    return $allResults
}

POST with File Upload

$filePath = "C:\data\upload.json"
$fileContent = Get-Content $filePath -Raw

$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer $token"
}

$response = Invoke-RestMethod -Uri "https://api.example.com/upload" `
    -Method Post `
    -Headers $headers `
    -Body $fileContent

Invoke-WebRequest: When You Need More Control

For scenarios requiring full HTTP response details:

# Get full response
$response = Invoke-WebRequest -Uri "https://api.example.com/data"

# Access response details
$response.StatusCode        # 200
$response.StatusDescription # OK
$response.Headers           # Response headers
$response.Content           # Raw content
$response.RawContent        # Full HTTP response

# Parse JSON manually
$data = $response.Content | ConvertFrom-Json

Downloading Files

# Download file
Invoke-WebRequest -Uri "https://example.com/file.zip" -OutFile "C:\Downloads\file.zip"

# With progress
$ProgressPreference = 'Continue'
Invoke-WebRequest -Uri "https://example.com/largefile.zip" -OutFile "largefile.zip"

Error Handling for API Calls

function Invoke-ApiWithRetry {
    param(
        [string]$Uri,
        [hashtable]$Headers,
        [int]$MaxRetries = 3
    )
    
    $attempt = 0
    
    while ($attempt -lt $MaxRetries) {
        try {
            $attempt++
            
            $response = Invoke-RestMethod -Uri $Uri -Headers $Headers -ErrorAction Stop
            return $response
        }
        catch {
            if ($_.Exception.Response.StatusCode -eq 429) {
                # Rate limited
                $retryAfter = $_.Exception.Response.Headers['Retry-After']
                Write-Warning "Rate limited. Waiting $retryAfter seconds..."
                Start-Sleep -Seconds $retryAfter
            }
            elseif ($attempt -lt $MaxRetries) {
                Write-Warning "Attempt $attempt failed. Retrying..."
                Start-Sleep -Seconds (5 * $attempt)
            }
            else {
                Write-Error "All $MaxRetries attempts failed: $_"
                throw
            }
        }
    }
}

Rate Limiting

function Invoke-WithRateLimit {
    param(
        [string[]]$Uris,
        [int]$RequestsPerMinute = 60
    )
    
    $delayMs = [math]::Ceiling(60000 / $RequestsPerMinute)
    $results = @()
    
    foreach ($uri in $Uris) {
        $results += Invoke-RestMethod -Uri $uri
        Start-Sleep -Milliseconds $delayMs
    }
    
    return $results
}

Real-World Integration: Automated Monitoring

# Monitor API health and send alerts
$endpoints = @(
    @{Name="Production API"; Url="https://api.prod.example.com/health"},
    @{Name="Staging API"; Url="https://api.staging.example.com/health"},
    @{Name="Database API"; Url="https://db.api.example.com/health"}
)

foreach ($endpoint in $endpoints) {
    try {
        $start = Get-Date
        $response = Invoke-RestMethod -Uri $endpoint.Url -TimeoutSec 10
        $duration = ((Get-Date) - $start).TotalMilliseconds
        
        if ($response.status -ne "healthy") {
            # Send alert
            $slackWebhook = $env:SLACK_WEBHOOK
            $message = @{
                text = "⚠️ $($endpoint.Name) is unhealthy: $($response.status)"
            } | ConvertTo-Json
            
            Invoke-RestMethod -Uri $slackWebhook -Method Post -Body $message -ContentType "application/json"
        }
        else {
            Write-Host "✓ $($endpoint.Name): Healthy (${duration}ms)"
        }
    }
    catch {
        Write-Error "✗ $($endpoint.Name): Failed - $_"
    }
}

Common Pitfalls

1. Not Handling Rate Limits

Problem: API blocks after too many requests Solution: Implement retry logic with delays

2. Hardcoded Credentials

Problem: Security risk Solution: Use environment variables or secure storage

# Bad
$token = "hardcoded-token"

# Good
$token = $env:API_TOKEN

3. Not Checking HTTP Status Codes

Problem: Assuming success Solution: Check status and handle errors

Key Takeaways

• Invoke-RestMethod: Automatic JSON parsing

• Invoke-WebRequest: Full HTTP response control

• Authentication: Bearer, Basic, API Keys

• Error handling: Retry logic for reliability

• Rate limiting: Respect API limits

• Security: Never hardcode credentials

What You've Learned

✅ Making REST API calls with PowerShell ✅ Authentication methods (Bearer, Basic, API Key) ✅ Working with JSON data ✅ Error handling and retry logic ✅ Real-world API integrations ✅ Rate limiting and best practices

Next Steps

You can now integrate with any API. Let's focus on cloud automation. In PowerShell for Azure, you'll learn:

• Az PowerShell module

• Managing Azure resources

• Azure automation patterns

• Cost optimization scripts

Bring your PowerShell skills to the cloud.

---

Ready for Azure? Continue to PowerShell for Azure →