Créer une API REST avec PowerShell et le module Pode

Sophie referme le script de consultation de l’API de ticketing : « On a vu comment interroger une API extérieure. Mais si je te demandais l’inverse : exposer notre propre rapport de supervision, pour qu’un autre outil du service IT — ou même un simple navigateur — puisse venir le consulter directement, sans avoir à lancer un script à la main ? » C’est exactement ce que permet le module Pode : transformer PowerShell en un véritable serveur web, capable d’exposer sa propre API.

Installer Pode

Comme tout module tiers, Pode s’installe depuis la PowerShell Gallery (vue en 6.1) :

Install-Module -Name Pode -Scope CurrentUser

Comme tout ce qui touche aux API vu depuis le début de cette section, Pode fonctionne à l’identique sur Windows, Linux et macOS — un vrai serveur web Nordika pourrait tourner sur une petite VM Linux, avec exactement le même script PowerShell qu’en développement sur un poste Windows.

Un premier serveur minimal

Un serveur Pode s’organise autour d’un bloc Start-PodeServer, à l’intérieur duquel on déclare des routes — chacune associant une méthode HTTP (vue en 9.1) et un chemin d’URL à un bloc de code PowerShell :

Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    Add-PodeRoute -Method Get -Path '/api/ping' -ScriptBlock {
        Write-PodeJsonResponse -Value @{ message = "Nordika API opérationnelle" }
    }
}

Une fois ce script lancé, une simple requête suffit à tester la route, depuis n’importe quel outil, y compris PowerShell lui-même (avec les cmdlets vues en 9.1) :

Invoke-RestMethod -Uri "http://localhost:8080/api/ping"

Write-PodeJsonResponse joue ici le rôle inverse de ConvertFrom-Json vu en 9.1 : elle transforme un objet ou une hashtable PowerShell en réponse JSON, prête à être consommée par n’importe quel client.

Exposer le rapport de supervision via une route

En reprenant directement le script de supervision multi-serveurs du TP N°3 (section 7), on peut l’exposer comme une véritable route d’API, plutôt que de se limiter à un fichier ou un email (section 8) :

Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    Add-PodeRoute -Method Get -Path '/api/supervision' -ScriptBlock {
        $serveurs = Get-Content -Path "C:\Nordika\Scripts\serveurs.txt"

        $resultats = Invoke-Command -ComputerName $serveurs -ScriptBlock {
            $service = Get-Service -Name "Spooler" -ErrorAction SilentlyContinue
            $volume = Get-Volume -DriveLetter C
            [PSCustomObject]@{
                Serveur             = $env:COMPUTERNAME
                StatutService       = $service.Status
                EspaceLibrePourcent = [math]::Round(($volume.SizeRemaining / $volume.Size) * 100, 1)
            }
        } -ErrorAction SilentlyContinue

        Write-PodeJsonResponse -Value $resultats
    }
}

N’importe quel outil du service IT — un tableau de bord interne, un script d’un collègue, ou même un navigateur — peut désormais consulter http://localhost:8080/api/supervision et recevoir le rapport à jour, calculé à la demande.

Des routes avec paramètres

Comme pour une vraie API professionnelle (celle de ticketing vue en 9.1), une route Pode peut accepter des paramètres dans l’URL :

Add-PodeRoute -Method Get -Path '/api/supervision/:serveur' -ScriptBlock {
    $nomServeur = $WebEvent.Parameters['serveur']

    $resultat = Invoke-Command -ComputerName $nomServeur -ScriptBlock {
        Get-Service -Name "Spooler" | Select-Object -Property Name, Status
    }

    Write-PodeJsonResponse -Value $resultat
}

Une requête vers http://localhost:8080/api/supervision/SRV-01 ne renverrait alors que le résultat pour ce serveur précis, $WebEvent.Parameters récupérant la portion :serveur de l’URL appelée.

Sécuriser une API Pode (aperçu)

Exactement comme pour l’API de ticketing en 9.2, une API Pode destinée à autre chose qu’un test local mérite une authentification :

Start-PodeServer {
    Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http

    New-PodeAuthScheme -ApiKey -Location Header | Add-PodeAuth -Name 'CleAPI' -ScriptBlock {
        param($cle)
        if ($cle -eq $env:NORDIKA_API_INTERNE_KEY) {
            return @{ User = @{ Nom = "ServiceIT" } }
        }
        return $null
    }

    Add-PodeRoute -Method Get -Path '/api/supervision' -Authentication 'CleAPI' -ScriptBlock {
        # ... même logique que précédemment
    }
}

On retrouve ici le même principe fondamental posé en 9.2 : la clé attendue (NORDIKA_API_INTERNE_KEY) provient d’une variable d’environnement, jamais codée en dur dans le script.

Retour d’expérience terrain : Pode reste un excellent choix pour des API internes légères — un tableau de bord de supervision, un petit webhook, une intégration entre deux outils déjà en PowerShell dans l’entreprise. Pour une API destinée à un trafic important ou public, on s’orientera plutôt vers des frameworks dédiés (ASP.NET Core, par exemple), mais pour l’immense majorité des besoins d’automatisation internes à un service IT comme celui de Nordika, Pode évite d’avoir à sortir de l’écosystème PowerShell déjà maîtrisé depuis le début de cette formation.

Source officielle : la documentation complète de Pode détaille l’ensemble des fonctionnalités du module : middlewares, sessions, WebSockets, génération automatique de documentation OpenAPI/Swagger — largement suffisant pour explorer au-delà de cette introduction.

Cette leçon referme la boucle de toute la section 9 : vous savez désormais consommer une API externe (9.1), vous authentifier auprès d’elle (9.2), gérer sa fiabilité réelle (9.3), et enfin, construire la vôtre pour que d’autres puissent consommer les données de Nordika en retour.

Dans la prochaine leçon, un TP pour mettre en pratique l’ensemble de la section : un webhook d’alerte, puis une mini-API de consultation du rapport de supervision.