9.1 : Invoke-RestMethod vs Invoke-WebRequest : consommer une API REST

Sophie ouvre un nouveau chantier : « Nordika utilise maintenant un service météo externe pour anticiper les pics de charge sur la climatisation des salles serveur. Et notre outil de ticketing a une API qu’on pourrait interroger directement, plutôt que d’aller cliquer dans son interface web. » Tout ce qu’on a vu depuis la section 1 concernait le poste local ou le parc interne de Nordika. Cette section ouvre l’atelier vers l’extérieur : consommer des services web, via leur API REST.

Point important dans la continuité de la leçon 1.3 : contrairement au Registre, aux comptes locaux ou à ActiveDirectory, tout ce qui concerne les API web fonctionne rigoureusement à l’identique sur Windows, Linux et macOS. Ces cmdlets ne dépendent d’aucune brique système propre à un OS.

Invoke-RestMethod : la cmdlet pensée pour les API

Invoke-RestMethod est la cmdlet à privilégier dès qu’on sait qu’on s’adresse à une API qui renvoie des données structurées, typiquement au format JSON :

$reponse = Invoke-RestMethod -Uri "https://api.nordika-meteo.local/previsions?ville=Bourges"
$reponse

Le point remarquable, cohérent avec tout ce qui a été répété depuis la leçon 1.2 : Invoke-RestMethod désérialise automatiquement le JSON reçu en un véritable objet PowerShell. Pas besoin de parser du texte à la main :

$reponse.temperature
$reponse.previsions | Where-Object { $_.risqueGel -eq $true }

Vous retrouvez ici exactement le même réflexe que Get-Member (leçon 2.2), Where-Object (2.4) ou Sort-Object : une réponse d’API devient une pièce comme une autre sur le tapis roulant, avec ses propres propriétés.

Invoke-WebRequest : quand on a besoin de plus que les données

Invoke-WebRequest renvoie un objet plus complet, incluant le code de statut HTTP, les en-têtes de réponse, et le contenu brut — utile quand on a besoin de ces informations, ou quand la réponse n’est pas du JSON pur (une page HTML, un fichier binaire) :

$reponse = Invoke-WebRequest -Uri "https://api.nordika-meteo.local/previsions?ville=Bourges"

$reponse.StatusCode        # 200, 404, 500...
$reponse.Headers           # Les en-têtes HTTP de la réponse
$reponse.Content           # Le contenu brut, en texte

Pour obtenir des objets exploitables depuis ce contenu brut, il faut alors convertir soi-même le JSON, ce qu’Invoke-RestMethod fait automatiquement :

$donnees = $reponse.Content | ConvertFrom-Json

Règle simple à retenir : si vous savez déjà que l’API renvoie du JSON et que seules les données vous intéressent, Invoke-RestMethod va droit au but. Si vous avez besoin du code de statut HTTP, des en-têtes, ou si le format de réponse est incertain, Invoke-WebRequest donne accès à l’ensemble de la réponse brute.

Les verbes HTTP : GET, POST, PUT, DELETE

Une API REST s’organise autour de verbes HTTP, qui rappellent volontairement la convention Verbe-Nom vue en 2.1 (même si ce sont deux conventions distinctes, l’une pour PowerShell, l’autre pour le web) :

# GET : récupérer une donnée (comportement par défaut)
Invoke-RestMethod -Uri "https://api.nordika-ticketing.local/tickets/123" -Method Get

# POST : créer une nouvelle ressource
$nouveauTicket = @{
    titre  = "Imprimante hors service - Étage 2"
    priorite = "Haute"
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://api.nordika-ticketing.local/tickets" `
                   -Method Post `
                   -Body $nouveauTicket `
                   -ContentType "application/json"

ConvertTo-Json (l’inverse de ConvertFrom-Json vu plus haut) transforme une hashtable PowerShell (section 3) en chaîne JSON, prête à être envoyée dans le corps (-Body) de la requête.

# PUT : mettre à jour une ressource existante
Invoke-RestMethod -Uri "https://api.nordika-ticketing.local/tickets/123" `
                   -Method Put `
                   -Body (@{ statut = "Résolu" } | ConvertTo-Json) `
                   -ContentType "application/json"

# DELETE : supprimer une ressource
Invoke-RestMethod -Uri "https://api.nordika-ticketing.local/tickets/123" -Method Delete

Un exemple concret Nordika

$previsions = Invoke-RestMethod -Uri "https://api.nordika-meteo.local/previsions?ville=Bourges"

$risqueGel = $previsions.previsions | Where-Object { $_.temperatureMin -lt 2 }

if ($risqueGel) {
    Write-Warning "Risque de gel détecté : vérifier le chauffage de la salle serveur"
}

Ce script, une fois planifié comme vu en section 8, pourrait alerter automatiquement Sophie avant une nuit à risque pour la climatisation des salles serveur.

Retour d’expérience terrain : face à une API inconnue, le premier réflexe à adopter n’est pas de foncer sur Invoke-RestMethod, mais de consulter sa documentation (souvent disponible en Swagger/OpenAPI) pour connaître le format exact attendu en entrée, et le format réellement renvoyé en sortie. Une hypothèse erronée sur la structure du JSON attendu est la cause la plus fréquente d’échec silencieux ou de résultat incohérent lors des premiers tests d’intégration à une nouvelle API.

Source officielle : la documentation Microsoft Invoke-RestMethod et Invoke-WebRequest (accessible via Get-Help Invoke-RestMethod -Online, réflexe vu en leçon 1.4) détaille l’ensemble des paramètres disponibles, notamment la gestion de la pagination et de l’authentification, sujets approfondis dans les deux prochaines leçons.

Dans la prochaine leçon, on aborde un sujet indissociable de toute API sérieuse : l’authentification, avec les clés API et les tokens Bearer.