API-driven Systems

Automating API-Driven Systems

Modern enterprise environments often rely on REST APIs to integrate with cloud platforms (e.g., Azure, AWS), third-party tools (e.g., GitHub, Jira), and custom backend services. PowerShell provides robust capabilities to automate interactions with these systems using Invoke-RestMethod, Invoke-WebRequest, and custom headers. This section demonstrates how to build scripts that securely and efficiently consume and manipulate API-driven systems.

---

Understanding REST API Fundamentals

REST (Representational State Transfer) APIs use standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources. PowerShell scripts can automate these interactions by constructing HTTP requests with the correct headers, payloads, and authentication.

Example: Fetching data from a public API

$response = Invoke-RestMethod -Uri 'https://api.public.data/v1/resources' -Method Get
$response | Format-Table

---

Authentication Strategies

Most APIs require authentication to enforce access control. Common methods include:

1. API Keys

Add the key to request headers:

$headers = @{
    'Authorization' = 'Bearer YOUR_API_KEY'
}
Invoke-RestMethod -Uri 'https://api.example.com/data' -Headers $headers

2. OAuth 2.0 (Token-Based)

Acquire a token via an authorization endpoint and include it in headers:

$token = Invoke-RestMethod -Uri 'https://auth.example.com/token' -Method Post -Body @{
    client_id    = 'your_client_id'
    client_secret = 'your_secret'
    grant_type    = 'client_credentials'
}
$headers = @{
    'Authorization' = "Bearer $($token.access_token)"
}

3. Integrated Windows Authentication (IWA)

Use for on-premises services:

Invoke-RestMethod -Uri 'https://internal-api.company.com/api' -UseDefaultCredentials

---

Making HTTP Requests with Invoke-RestMethod

The Invoke-RestMethod cmdlet simplifies REST interactions. Use it to send requests and parse JSON responses.

Example: Creating a Resource (POST)

$body = @{
    name = 'ExampleResource'
    status = 'active'
} | ConvertTo-Json

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

Example: Updating a Resource (PUT)

$id = '12345'
$body = @{
    id = $id
    status = 'inactive'
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://api.example.com/resources/$id" -Method Put -Body $body

---

Handling Pagination and Rate Limits

Many APIs return paginated results or enforce rate limits. Use loops and headers to navigate these constraints.

Example: Iterating through paginated results

$page = 1
do {
    $uri = "https://api.example.com/data?page=$page"
    $response = Invoke-RestMethod -Uri $uri
    if ($response.items) {
        $response.items | ForEach-Object { Process-Item $_ }
    }
    $page++
} while ($response.next_page -ne $null)

---

Error Handling and Debugging

Use try/catch blocks to handle API errors gracefully:

try {
    $response = Invoke-RestMethod -Uri 'https://api.example.com/data' -Method Get
} catch {
    Write-Error "API request failed: $($_.Exception.Message)"
    exit 1
}

Log detailed responses for debugging:

$response = Invoke-RestMethod -Uri 'https://api.example.com/data' -Method Get -Verbose
$response | Out-File 'api_response.log'

---

Best Practices

• Secure credentials: Store secrets in Azure Key Vault, environment variables, or encrypted files.
• Use ConvertTo-Json/ConvertFrom-Json: Simplify payload construction and response parsing.
• Validate responses: Check for HTTP status codes (e.g., 200 OK, 404 Not Found).
• Respect rate limits: Implement delays between requests using Start-Sleep.

---

Key takeaways

• Use Invoke-RestMethod to interact with REST APIs, leveraging HTTP methods and headers for authentication.
• Secure API keys and tokens using environment variables or secret management tools.
• Handle pagination, rate limits, and errors with loops, try/catch, and logging.
• Always validate responses and use JSON serialization for complex payloads.